Overview - Supplier API
The KYA Research Supplier API can be used to connect your panel into the KYA Research Intelligent Survey Tool to automatically receive Research Sample orders. This API document describes the usage and resources needed for integrating with Sample API
How to Use Supplier API
The KYA Research Supplier API is a REST based API. The URL structure is as follow
Base Urls
Staging Url : https://staging.kyaresearch.com
Production Url : https://api.kyaresearch.com
Request Format
{Method} {Base URI}/{Module}/{API Version}/{Resource}
Example : GET https://staging.kyaresearch.com/suppliers/v1/surveys
Request Methods
GET : Method used for fetch data
POST : Method used for update or submit data.
Authentication and API Responses
Our APIs use a HTTP Authorization header for authentication. Every call should have a header Authorization:
{{APIkey}}, payload:{{APIPayload}} and Content-Type: 'application/json'. Ensure that the key you are passing is the correct key for the environment. We built it on RESTful
principles, the API uses HTTP methods and verbs. Requests should be made using JSON, and JSON is returned by all
responses.
Example: headers: { 'Authorization': 'APIkey', 'payload': 'APIPayload', 'Content-Type': 'application/json' }
The API uses standard HTTP status codes to indicate success or failure of an API Request
and response data are in application/json format. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error caused by the information provided (i.e., a required parameter was omitted, a method was not found, etc.), and codes in the 5xx range indicate an error with KYA Research's servers (these are rare).
| Parameter | Value |
|---|---|
| apiStatus | 0 (failure) or 1 (success) |
| apiMessages | A detailed error message describing what went wrong |
Status Code Summary
| 200 | Everything Worked As Expected |
| 400 | Bad Request |
| 403 | Invalid Access Token |
| 404 | Resources Not Found |
| 5xx | Something Went Wrong On KYA Research |
Change Log - Last updated : 27-March-2024
Click here to download complete Profile Library excel file.
Get Languages List
This will return all available languages we support.
API Sample
GET https://staging.kyaresearch.com/suppliers/v1/getLanguages/
curl -X GET -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -H "payload: YOUR_API_PAYLOAD_HERE" -i https://staging.kyaresearch.com/suppliers/v1/getLanguages/
API Sample Response
{
"apiStatus":1,
"version":1,
"apiMessages":"getLanguages successful.",
"languages":[
{"languageID":"41","languageName":"Abkhaz","languageCode2":"ab"},{"languageID":"2","languageName":"Afar","languageCode2":"aa"},{"languageID":"3","languageName":"Afrikaans","languageCode2":"af"},{"languageID":"4","languageName":"Akan","languageCode2":"ak"},{"languageID":"5","languageName":"Albanian","languageCode2":"sq"}
]
}
Get Profile Categories List
This will return all profile categories list.
API Sample
GET https://staging.kyaresearch.com/suppliers/v1/getProfileCategories/
curl -X GET -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -H "payload: YOUR_API_PAYLOAD_HERE" -i https://staging.kyaresearch.com/suppliers/v1/getProfileCategories/
API Sample Response
{
"apiStatus":1,
"version":1,
"apiMessages":"getProfileCategories successful.",
"languages":[
{"languageID":"41","languageName":"Abkhaz","languageCode2":"ab"},{"languageID":"2","languageName":"Afar","languageCode2":"aa"},{"languageID":"3","languageName":"Afrikaans","languageCode2":"af"},{"languageID":"4","languageName":"Akan","languageCode2":"ak"},{"languageID":"5","languageName":"Albanian","languageCode2":"sq"}
]
}
Get Active Survey(s) List
The Allocated Survey resource returns the number of allocated surveys available to for your account.
Arguments
| Variable | Type | Required | Description |
|---|---|---|---|
| country | String | False | Country ISO Code (2 Char) associated with the survey. |
| language | String | False | Language ISO Code (2 Char) associated with the survey. |
This API call accepts two Arguments to filter available surveys based on required country and/or language.
API Sample (Without Filter)
GET https://staging.kyaresearch.com/suppliers/v1/surveys/
curl -X GET -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -H "payload: YOUR_API_PAYLOAD_HERE" -i https://staging.kyaresearch.com/suppliers/v1/surveys/
API Sample Response
{ "apiStatus": 1, "version": 1, "apiMessages": "GetSurveyList successful.", "surveys": [ { "surveyID": "66882", "surveyCPI": "0.40", "surveyTargetCount": "210", "LOI": "1", "IR": "30", "countries_iso_code_2": "IN", "language_iso_code_2": "en", "language_country_code": "en-IN", "project_supported_device": "1", "studyType": "B2B" }, { "surveyID": "66883", "surveyCPI": "0.40", "surveyTargetCount": "200", "LOI": "15", "IR": "30", "countries_iso_code_2": "IN", "language_iso_code_2": "en", "language_country_code": "en-IN", "project_supported_device": "1", "studyType": "B2B" } ] }project_supported_device value definition
1 : Desktop Devices Only
2 : Mobile/Tablet Devices Only
3 : All Devices
API Sample (With Country Filter)
GET https://staging.kyaresearch.com/suppliers/v1/surveys/?country=US
curl -X GET -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -H "payload: YOUR_API_PAYLOAD_HERE" -i https://staging.kyaresearch.com/suppliers/v1/surveys/?country=US
API Sample Response
{
"apiStatus": 1,
"version": 1,
"apiMessages": "GetSurveyList successful.",
"surveys": [
{
"surveyID": "66881",
"surveyCPI": "0.40",
"surveyTargetCount": "150",
"LOI": "10",
"IR": "30",
"countries_iso_code_2": "US",
"language_iso_code_2": "en",
"language_country_code": "en-US",
"project_supported_device": "1",
"studyType": "B2B"
}
]
}
API Sample (With Language Filter)
GET https://staging.kyaresearch.com/suppliers/v1/surveys/?language=en
curl -X GET -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -H "payload: YOUR_API_PAYLOAD_HERE" -i https://staging.kyaresearch.com/suppliers/v1/surveys/?language=en
API Sample Response
{
"apiStatus": 1,
"version": 1,
"apiMessages": "GetSurveyList successful.",
"surveys": [
{
"surveyID": "66881",
"surveyCPI": "0.40",
"surveyTargetCount": "150",
"LOI": "10",
"IR": "30",
"countries_iso_code_2": "US",
"language_iso_code_2": "en",
"language_country_code": "en-US",
"project_supported_device": "1",
"studyType": "B2B"
},
{
"surveyID": "66882",
"surveyCPI": "0.40",
"surveyTargetCount": "210",
"LOI": "1",
"IR": "30",
"countries_iso_code_2": "IN",
"language_iso_code_2": "en",
"language_country_code": "en-IN",
"project_supported_device": "1",
"studyType": "B2B"
},
{
"surveyID": "66883",
"surveyCPI": "0.40",
"surveyTargetCount": "200",
"LOI": "15",
"IR": "30",
"countries_iso_code_2": "IN",
"language_iso_code_2": "en",
"language_country_code": "en-IN",
"project_supported_device": "1",
"studyType": "B2B"
}
]
}
API Sample (With Country and Language Filter)
GET https://staging.kyaresearch.com/suppliers/v1/surveys/?country=US&language=en
curl -X GET -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -H "payload: YOUR_API_PAYLOAD_HERE" -i https://staging.kyaresearch.com/suppliers/v1/surveys/?country=US&language=en
API Sample Response
{
"apiStatus": 1,
"version": 1,
"apiMessages": "GetSurveyList successful.",
"surveys": [
{
"surveyID": "66881",
"surveyCPI": "0.40",
"surveyTargetCount": "150",
"LOI": "10",
"IR": "30",
"countries_iso_code_2": "US",
"language_iso_code_2": "en",
"language_country_code": "en-US",
"project_supported_device": "1",
"studyType": "B2B"
}
]
}
Get Surveys Current Quota and Status
The quotas resource returns the number of completes available and its current status to you for each query survey. You can send multiple surveyIDs seperated by "," or a single surveyID.
Arguments
| Variable | Type | Required | Description |
|---|---|---|---|
| SurveyIDs | string | True | Unique number associated with the survey. |
API Sample
POST https://staging.kyaresearch.com/suppliers/v1/quotaStatus/
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -H "payload: YOUR_API_PAYLOAD_HERE" -X POST --data '{"surveyIDs":"21,22,23"}'
API Sample Response
{
"apiStatus": 1,
"version": 1,
"apiMessages": "Surveys Quota and Status is fetched.",
"surveyInfo": [
{
"surveyID": "66883",
"surveyStatus": "2",
"surveyTargetCount": "0",
"surveyCPI": "0.40",
"Quota": {
"1161": {
"conditions": [
{
"profileQuestionKey": "employment_status",
"profileAnswerKey": "employment_status_001348",
"OptionText": "Employed full-time"
},
{
"profileQuestionKey": "age",
"profileAnswerKey": " ",
"min": "18",
"max": "35"
}
],
"remainingQuota": [
"100"
]
},
"1162": {
"conditions": [
{
"profileQuestionKey": "employment_status",
"profileAnswerKey": "employment_status_001350",
"OptionText": "Self-employed full-time"
},
{
"profileQuestionKey": "age",
"profileAnswerKey": " ",
"min": "40",
"max": "60"
}
],
"remainingQuota": [
"50"
]
},
"1163": {
"conditions": [
{
"profileQuestionKey": "employment_status",
"profileAnswerKey": "employment_status_001349",
"OptionText": "Employed part-time"
},
{
"profileQuestionKey": "gender",
"profileAnswerKey": "gender_002",
"OptionText": "Female"
},
{
"profileQuestionKey": "age",
"profileAnswerKey": " ",
"min": "18",
"max": "35"
}
],
"remainingQuota": [
"25"
]
},
"1164": {
"conditions": [
{
"profileQuestionKey": "employment_status",
"profileAnswerKey": "employment_status_001349",
"OptionText": "Employed part-time"
},
{
"profileQuestionKey": "gender",
"profileAnswerKey": "gender_001",
"OptionText": "Male"
},
{
"profileQuestionKey": "age",
"profileAnswerKey": " ",
"min": "18",
"max": "35"
}
],
"remainingQuota": [
"25"
]
}
}
}
]
}
* In above result survey status is returned as integer value
0 Survey not registered
1 Survey is Live.
2 Survey is on hold or closed.
Get Survey Qualification
This API will allow supplier to get qualifications associated with each survey. Each qualification will be returned with targeting criteria.
Arguments
| Variable | Type | Required | Description |
|---|---|---|---|
| surveyID | Integer | True | Unique number associated with the survey. |
API Sample
POST https://staging.kyaresearch.com/suppliers/v1/getQualification
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -H "payload: YOUR_API_PAYLOAD_HERE" -X POST --data '{"surveyID":1}'
API Sample Response
{
"apiStatus": 1,
"version": 1,
"apiMessages": "GetSurveyQualification successful.",
"targeting": {
"age": [
{
"optionID": 1,
"profileAnswerKey": " ",
"min": "18",
"max": "35"
},
{
"optionID": 2,
"profileAnswerKey": " ",
"min": "40",
"max": "60"
}
],
"gender": [
{
"optionID": 1,
"profileAnswerKey": "gender_001",
"OptionText": "Male"
},
{
"optionID": 2,
"profileAnswerKey": "gender_002",
"OptionText": "Female"
}
],
"employment_status": [
{
"optionID": 1,
"profileAnswerKey": "employment_status_001348",
"OptionText": "Employed full-time"
},
{
"optionID": 2,
"profileAnswerKey": "employment_status_001349",
"OptionText": "Employed part-time"
},
{
"optionID": 3,
"profileAnswerKey": "employment_status_001350",
"OptionText": "Self-employed full-time"
},
{
"optionID": 4,
"profileAnswerKey": "employment_status_001357",
"OptionText": "Student"
}
]
}
}
Register Survey Entry Links
The Entry links API call will update your Success Url, Terminate Url and Quotafull Url and returns the Survey Entry Link.
Arguments
| Variable | Type | Required | Description |
|---|---|---|---|
| SurveyID | Integer | True | Unique number associated with the survey. |
| SuccessLink | String | True | Link used to notify when survey status is completed. |
| disQualifiedLink | String | True | Link used to notify when survey status is disqualified. |
| TermLink | String | True | Link used to notify when survey status is terminated. |
| OverQuotaLink | String | True | Link used to notify when survey status is over quota. |
| useStaticLink | Integer | True | 0 for Dynamic Urls or 1 for Static Redirect Urls. |
API Sample
POST https://staging.kyaresearch.com/suppliers/v1/register/
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -H "payload: YOUR_API_PAYLOAD_HERE" -X
POST --data '{
"surveyID":21,
"SuccessLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"disQualifiedLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"TermLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"OverQuotaLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"useStaticLink":0
}'
API Sample Response
{
"apiStatus": 1,
"version": 1,
"apiMessages": "SurveyEntryLinks successfully registered.",
"surveyInfo": [{
"surveyID": 21,
"SurveyEntryUrl": "https:\/\/kya.kyaresearch.com\/surveyInitiate.php?gid=MTQ3LTE2MTA=&pid={{PANELIST IDENTIFIER}}&ext={{PANEL MISC DATA}}&reconnectID={{RECONNECTID}}",
"surveyTargetCount": 200,
"surveyCPI": "8.80"
}]
}
* In above SurveyEntryUrl having two optional parameters which are ext and reconnectID
ext is used to passed any additional parameters you required to pass back in your entry urls.
reconnectID is used we required recontact for certain panel members of yours.
Register Multiple Survey Entry Links
The Multiple Entry links API call will update your Success Urls, Terminate Urls and Quotafull Urls and returns the Survey Entry Links.
Arguments
| Variable | Type | Required | Description |
|---|---|---|---|
| Surveys | Json Array | True | Containing Desired Unique number associated with the surveys. |
| Json Array should contains follwoing variables | |||
| SurveyID | Integer | True | Unique number associated with the survey. |
| SuccessLink | String | False | Link used to notify when survey status is completed. |
| disQualifiedLink | String | False | Link used to notify when survey status is disqualified. |
| TermLink | String | False | Link used to notify when survey status is terminated. |
| OverQuotaLink | String | False | Link used to notify when survey status is over quota. |
| useStaticLink | Integer | True | 0 for Dynamic Urls or 1 for Static Redirect Urls. |
API Sample
POST https://staging.kyaresearch.com/suppliers/v1/registerMultiple/
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -H "payload: YOUR_API_PAYLOAD_HERE" -X
POST --data '{
"Surveys": [
{
"surveyID": 21,
"SuccessLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"disQualifiedLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"TermLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"OverQuotaLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"useStaticLink":0
},
{
"surveyID": 22,
"SuccessLink": "",
"disQualifiedLink": "",
"TermLink": "",
"OverQuotaLink": "",
"useStaticLink":1
},
{
"surveyID": 23,
"SuccessLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"disQualifiedLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"TermLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"OverQuotaLink": "https://kya.kyaresearch.com/surveyProcess.php?pid={{PANELIST IDENTIFIER}}",
"useStaticLink":0
}
]
}'
API Sample Response
{
"apiStatus": 1,
"version": 1,
"apiMessages": "Multiple SurveyEntryLinks successfully processed.",
"surveyInfo": [
{
"surveyID": 21,
"surveyStatus": "SurveyEntryLink successfully registered.",
"SurveyEntryUrl": "https:\/\/kya.kyaresearch.com\/surveyInitiate.php?gid=MTQ3LTE2MTA=&pid={{PANELIST IDENTIFIER}}&ext={{PANEL MISC DATA}}&reconnectID={{RECONNECTID}}",
"surveyTargetCount": 200,
"surveyCPI": "8.80"
},
{
"surveyID": 22,
"surveyStatus": "Not Live",
"SurveyEntryUrl": "",
"surveyTargetCount": "",
"surveyCPI": ""
},
{
"surveyID": 23,
"surveyStatus": "Not Live",
"SurveyEntryUrl": "",
"surveyTargetCount": "",
"surveyCPI": ""
}
]
}
* In above SurveyEntryUrl having two optional parameters which are ext and reconnectID
ext is used to passed any additional parameters you required to pass back in your entry urls.
reconnectID is used we required recontact for certain panel members of yours.
Contact Us
Feel free to contact us for any query regarding the API usage. We are also like to hear from you about your liking and suggestions.
Please drop an email to info@kyaresearch.com