Overview
Welcome to the official engineering documentation for Ketomr.
-
The Supply API allows seamless integration with Ketomr’s global survey network, providing real-time access to active survey opportunities.
Built on RESTful principles, the API is engineered for smooth partner integration, enabling complete automation and flexible management of supply-side traffic.
-
This API uses JSON for all request and response formats, ensuring efficient and standardized data communication.
Key features include:
- Real-time survey availability and status tracking
- Quota and qualification data retrieval
-
By integrating with the Ketomr Supply API, partners gain greater control over traffic flow, improved visibility into performance trends,
and improved optimization across different devices, regions, and audience segments.
-
The Ketomr Supply API is a scalable and data-driven solution designed to support high-volume, real-time survey distribution and management.
List of Allocated Surveys
supplier/send_supplier_data
Returns a list of all active (live) survey events in which the supplier has participation rights, either through an allocation or an entry link in the system.
Request
HEADER PARAMETERS
Supplierid
string
Required
The supplier’s unique ID.
Example: 2b60bC8284bcdaA50fd7d116Bb8e5b6
Token
string
Required
A unique hash passed in the request header, used to retrieve specific data or authorise access to a protected resource.
Example: 24e56c4435cb18503c7cb2da2b857c9df0daadcd4c34cdb8cbb949b4c4d83af9
RESPONSE PROPERTIES
project_code
string
The character string representing a unique Project Code.
Example: KETO01
project_name
string
The external name of the project.
Example: KETO01
country
string
A unique ID associated with the country of the project.
Example: United States
language
string
A unique ID associated with the language of the project.
Example: English
category
string
Represents the study type of the project, specifying its overall format and purpose.
Example: B2C/B2B/Healthcare
currency
string
The exact revenue paid to the supplier per complete (CPI) may vary depending on field conditions, such as interview length and the difficulty of reaching the target sample. The CPI amount will be provided in either USD or INR, based on the agreed currency for the project.
Example: USD
audience_type
boolean
Represents the study type of the project, specifying its overall format and purpose.
Example: yes/no
pii_collection
boolean
Indicates whether the project involves collecting any personal information from the respondent.
Example: yes/no
project_ir
integer
The IR (Incidence Rate) is calculated by comparing the number of respondents who qualify for the survey against those who do not. This percentage reflects the proportion of participants who meet the project’s eligibility criteria.
Example: 10
project_loi
integer
The average time (in minutes) allotted for a respondent to complete the survey.
Example: 5
cpi
boolean
The exact revenue paid to the supplier per complete. The CPI (Cost Per Interview) may vary in field due to changes in interview length and the difficulty of reaching the target sample.
Example: 1.0
quota
integer
Total number of completes needed for the project.
Example: 100
live_quota
integer
If the value is 0, there is no limit on clicks to achieve the quota.If greater than 0, only the specified number of clicks are permitted.
Example: 0
test_quota
integer
If the value is 0, there is no limit on clicks to achieve the quota.If greater than 0, only the specified number of clicks are permitted.
Example: 10
project_start_date
date
The scheduled date for the project to begin. This does not always represent a fixed start time, as the project may commence earlier or later depending on readiness and operational requirements.
Example: 2025-03-12
project_end_date
date
The planned date for the project to conclude. This does not necessarily represent a strict closure time, as the project may be extended or closed earlier based on completion status and requirements.
Example: 2025-03-22
live_url
string
This is the supplier-specific live project entry URL .
Example: https://example.com/survey?projectid=1111&supplierid=5056508&url=1&uid=[respondent_id]
test_url
string
This is the supplier-specific live project entry URL.
Example: https://example.com/survey?projectid=72728027&supplierid=5056508&url=0&uid=[respondent_id]
device_type
string
Indicates whether the project allows participation from desktop or mobile or tablet users.
Example: Desktop,Mobile,Tablet
target_spec
string
qualifications
array
RESPONSE SAMPLES
Options: Male
Quota: 10
Options: Female
Quota: 10
Options: Others
Quota: 10
", "qualifications": [ { "question_id": "4695", "control_type": "1", "option": [ { "option": 1 }, { "option": 2 }, { "option": 3 } ], "quota": [ { "option": 1, "quota": "10" }, { "option": 2, "quota": "10" }, { "option": 3, "quota": "10" } ] } ] } ] }
List of Supported Countries
get_master_data/country
This API call returns a list of all countries available in the system, typically used for targeting or localization within project.
Request
HEADER PARAMETERS
Token
string
Required
Token.
Example: 2b60bC8284bcdaA50fd7d116Bb8e5b6
RESPONSE PROPERTIES
Data
array
Provides a list of countries linked to the account.
Id
integer
The unique ID of a country.
Example: 1
short_name
string
short_name of the country.
Example: AF
name
string
The name of the country.
Example: Afghanistan
RESPONSE SAMPLES
List of Supported Languages
get_master_data/language
This API call returns a list of all languages available in the system, typically used for targeting or localization within surveys.
Request
HEADER PARAMETERS
Token
string
Required
Token.
Example: 2b60bC8284bcdaA50fd7d116Bb8e5b6
RESPONSE PROPERTIES
Date
array
Provides a list of languages linked to the account.
Id
integer
The unique ID of a language.
Example: 1
short_name
string
short_name of the language.
Example: AM
name
string
The name of the language.
Example: English
RESPONSE SAMPLES
List of Standard Qualifications
get_master_data/question
This API call returns a list of all standard qualification and qualification texts for the specified Country-Language pair.
Request
HEADER PARAMETERS
Token
string
Required
Token.
Example: 2b60bC8284bcdaA50fd7d116Bb8e5b6
Content-Type
string
Required
The content type of the request body.
Example: application/json
RESPONSE PROPERTIES
qualifications
array
Provides a standard list of qualifications linked to the account.
id
integer
The unique ID of a qualification.
Example: 2
country
integer
country id.
Example: 229
language
integer
language id.
Example: 5
title
string
The title of the qualification.
Example: Gender?
question
string
The tect of the qualification.
Example: Are you...?
control_type
string
The type of the qualification.
Example:
mapped_option
array
Options of the qualification.
Example: