The Source of Truth for Supply Chain Data

Integrate real-time inventory, logistics, and supply chain intelligence directly into your applications with the Trayistats Supply API.

View API Reference

Why Trayistats?

Built for developers who need reliability and speed at scale. We handle the complexity of global logistics data so you don't have to.

Low Latency

Engineered for speed with edge caching, delivering responses in under 50ms worldwide.

Global Coverage

Unified data model aggregating sources from over 120 countries and 500+ carriers.

Developer Friendly

Type-safe SDKs available for Node.js, Python, and Go. Comprehensive OpenAPI specs.

Quick Start Example

Fetch available surveys with a single API call.

GET /supply/api/available-surveys

cURLNode.jsPython

# Fetch available surveys

curl -X GET \
"https://surveys.trayistats.com/supply/api/available-surveys" \
-H "accept: application/json"

{
  "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"
      }
    ]
  }
}

Environments

Base URLs for the TrayiStats Supply API. Use the Sandbox environment for testing and integration.

Sandbox Endpoint

Testing

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

Production Endpoint

Live

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

Authentication Required

All endpoints require a valid API key passed in the header.

Best Practice

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: Value parts 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

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.

GET

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

Headers

Name	Type	Required
access-key	string	Yes

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

Survey Object

SurveyResponse

Field	Type	Description
surveyId	string \| null	Unique identifier for the survey opportunity. Can be null.
title	number	Internal title or ID of the survey.
completeGoal	number	Total number of completes desired.
CompleteRequired	number	The count of completes still required.
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.
IsPulledSurvey	number	Flag indicating if the survey is pulled (0 or 1).
link	string	The survey entry link with placeholders.

Response Codes

200 OK

Request was successful and returns a list of surveys.

400 Bad Request

Invalid query parameters supplied.

401 Unauthorized

API Key is missing or invalid.

429 Too Many Requests

Rate limit exceeded.

Example Response

Key

Value

CURL PREVIEW

RESPONSE

{
  "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

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

GET

https://surveys.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`

Query Parameters

Parameter	Type	Description
include_metadata	boolean	Whether to include aggregate statistics (view count, completion rate) in the response object. Defaults to `false`.
expand	array	Expand nested objects. Available values: `questions`, `theme`.

Survey Object

SurveyResponse

Field	Type	Description
surveyId	string \| null	Unique identifier for the survey opportunity. Can be null.
title	number	Internal title or ID of the survey.
completeGoal	number	Total number of completes desired.
CompleteRequired	number	The count of completes still required.
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.
IsPulledSurvey	number	Flag indicating if the survey is pulled (0 or 1).
link	string	The survey entry link with placeholders.

Response Codes

200 OK

Returns a Survey Object.

404 Not Found

If the survey with the provided surveyId does not exist.

Example Request

Key

Value

CURL PREVIEW

RESPONSE

{
  "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.

GET

https://surveys.trayistats.com/supply/api/survey-attributes

Query Parameters

Name	Type	Description
`survey_id`required	string	The unique identifier of the survey.
`include_inactive`	boolean	Include archived or inactive attributes. Defaults to false.
`limit`	integer	Maximum number of attributes to return. Max 100.

Attribute Object

Returns an array of objects with the following schema:

id

string

Unique identifier for the attribute.

name

string

The display name of the attribute (e.g., "Customer Satisfaction Score").

type

enum

The data type. One of: text, number, single_select, multi_select.

options

array<string>

Available options if type is select. Nullable.

created_at

timestamp

ISO 8601 formatted timestamp of creation.

Request

Key

Value

CURL PREVIEW

RESPONSE

{
  "success": true,
  "data": {
    "Total": "int",
    "Items": [
      {
        "attributeId": "int",
        "options": "array"
      }
    ]
  }
}

List all countries

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

GET

https://surveys.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 resource.
name	string	The common English name of the country.
iso_2	string	Two-letter ISO 3166-1 alpha-2 country code.
locale	string	Default locale code (e.g., 'en-US').
region	string	OptionalContinent or sub-region.

Response Codes

200 OK

Request was successful and returns a list of countries.

401 Unauthorized

API Key is missing or invalid.

Example Request

Key

Value

CURL PREVIEW

RESPONSE

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

Attributes Endpoint

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

GET

https://surveys.trayistats.com/supply/api/attributes

Query Parameters

Parameter	Type	Required
`locale_id`	string	Required

The ISO code for the country (e.g., en-US). Determines the language and specific attribute availability.

Common Errors

400Bad Request

Invalid locale_id provided.

401Unauthorized

Authentication token is missing or invalid.

Example Request

200 OK

Response

Key

Value

CURL PREVIEW

RESPONSE

{
  "success": true,
  "countryLocaleId": null,
  "data": {
    "Total": "int",
    "Items": [
      {
        "name": "string",
        "id": "int",
        "text": "string",
        "type": "string",
        "options": [
          {
            "id": "int",
            "text": "string"
          }
        ]
      }
    ]
  }
}

Survey Stats

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

GET

https://surveys.trayistats.com/supply/api/survey-stats

Query Parameters

Name	Type	Required
SurveyId	string	Yes

Stats Object

SurveyStatsResponse

Field	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 Codes

200 OK

Request was successful and returns a list of surveys.

400 Bad Request

Invalid query parameters supplied.

401 Unauthorized

API Key is missing or invalid.

429 Too Many Requests

Rate limit exceeded.

Request

Key

Value

CURL PREVIEW

RESPONSE

{
  "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

Retrieve your unique private key from the API settings page. This key acts as the salt for the hash generation.

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 Trayistats?

Low Latency

Global Coverage

Developer Friendly

Quick Start Example

Environments

Sandbox Endpoint

Production Endpoint

Best Practice

Survey & Attribute API Refresh Behavior

Qualification Parameters

Available Surveys API

Survey Attributes API

Attributes API

API Reference

Available Surveys

Headers

Survey Object

Response Codes

Example Response

Get Survey by ID

Path Parameters

Query Parameters

Survey Object

Response Codes

Example Request

Survey Attributes

Query Parameters

Attribute Object

Request

List all countries

The Country Object

Response Codes

Example Request

Attributes Endpoint

Query Parameters

Common Errors

Example Request

Response

Survey Stats

Query Parameters

Stats Object

Response 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