urlscan.io logo urlscan.io
SecurityTrails logo

apidocs.kyaresearch.com Open in urlscan Pro
35.200.243.85  Public Scan

Back to summary
URL: https://apidocs.kyaresearch.com/
Submission: On March 29 via api from US — Scanned from US

Form analysis 0 forms found in the DOM

Text Content

   API DOCUMENT

 * Overview
 * Using the API
 * Authentication & Response
 * Change Log
 * Api Integration
     
   * Qualification APIs
   * Qualification Languages
   * Qualification Categories
     
     
   * Survey APIs
   * Active Survey List
   * Get Quota
   * Get Qualification
   * Single Survey Entry Link
   * Multiple Survey Entry Link
 * Contact




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.

* If you would like to use Static Redirect Urls, Set useStaticLink value to 1.
In that case All links parameters can be blank, otherwise in case of Dynamic
Redirect Urls you have to provide each 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.

* If you would like to use Static Redirect Urls, Set useStaticLink value to 1.
In that case All links parameters can be blank, otherwise in case of Dynamic
Redirect Urls you have to provide each 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