;

API Reference and Usage Guide

Introduction

The MyOnlineSurveys API has been meticulously crafted to ensure predictability and consistency across all its resources. When interacting with the API, you can seamlessly send JSON data in the request body and receive JSON representations of the requested resources in return. We adhere to established HTTP response codes and verbs, providing a familiar and user-friendly experience.

To suit your specific needs, you can access the MyOnlineSurveys API in two distinct modes: the Sandbox mode, ideal for testing and experimentation, with the base URL http://s.my-onlinesurveys.com, and the Production mode, for live and real-world transactions, accessible at http://api.my-onlinesurveys.com.

This dual-mode approach empowers you to tailor your API interactions to match your development and deployment requirements effectively.

Authentication
OAuth 2.0 Token-Based Authentication
OAuth 2.0 is an industry-standard protocol for authorization and authentication. It allows a user or service, referred to as the "client," to access protected resources on behalf of a resource owner, with their permission. OAuth 2.0 employs the concept of access tokens to grant or deny access to these protected resources.
Obtaining an Access Token
To acquire an access token, you need to make a POST request to the token endpoint. This request should include specific parameters and headers.
Token Endpoint

http://pr.my-onlinesurveys.com/realms/prodigious/protocol/openid-connect/token

Request
curl --location 'http://pr.my-onlinesurveys.com/realms/prodigious/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=myonlinesurvey' \
--data-urlencode 'client_secret=jPf2r74pGptCB8cZ1MA0axa51gYOmdD9' \
--data-urlencode 'scope=openid' \
--data-urlencode 'grant_type=client_credentials'
Parameters
  • `client_id`(Required): Your Client ID provided to you by MyOnlineSurvey.
  • `client_secret`(Required): Unique Api Key provided to you by Myonlinesurvey.
  • `scope`(Required): The requested scope, i.e., openid.
  • `grant_type`(Required): Specifies the grant type as client_credentials
MyOnlineSurvey is a leading platform for creating and managing surveys, enabling you to collect crucial data and make informed decisions. Our user-friendly interface and robust features have made us a trusted partner for businesses of all sizes, market researchers, and institutions worldwide.
Response
Upon a successful request, the API will respond with a JSON object containing the access token and additional details.
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUI...",
"expires_in": 300,
"token_type": "Bearer",
"scope": "openid email profile"
}
Using the Access Token
The obtained access token can be used to authenticate your application when making subsequent API requests. Include the token in the Authorization header as follows:
curl --location 'https://api.my-onlinesurveys.com/resource' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUI...'
Create a Project
Create Project Endpoint

/v1/prodigious/project/create

Request
  • Method `post`
  • Headers
    • `Content-Type: application/json`
    • `Authorization: Bearer YOUR_ACCESS_TOKEN`
  • Body
    {
    "name": "testapiproject",
    "quota": 20
    }
  • Parameters
    • `name`(Required String): The name of the project.
    • `quota`(Required Integer): The project's quota.
Response
{
"projectId": "12345",
"name": "testapiproject",
"quota": 20,
"createdAt": "2023-09-10T12:34:56Z"
}
  • Response Parameters
    • `projectId`Unique Project Id allotted to each project.
    • `name`Name of the project
    • `quota`Quota set for the project created
    • `createdAt`Project Created At
Setup Survey
Setup Survey Endpoint

/v1/prodigious/survey/setup

Request
  • Method `post`
  • Headers
    • `Content-Type: application/json`
    • `Authorization: Bearer YOUR_ACCESS_TOKEN`
  • Body
    {
        "prj_code": 12345,
        "survey_link": "http://test.com/id/XXXXX",
        "criteriaRequest": [
            {
                "name": "gender",
                "value": ["female"]
            },
            {
                "name": "age",
                "value": ["20","25"]
            }
        ]
    }
  • Parameters
    • `prj_code`(Required Integer): Unique Project Id recived when created project.
    • `survey_link`(Required String): Survey Link
    • `criteriaRequest`(Required): Contain criteria to identify panlist who qualifies to take survey. For e.g as given above gender only female and age group of 20-25. Note value must be array of strings and for range values like age or icome it must contain start and end value of range like for age of 18 - 20 value will be value:["18"-20"]
Response
{
    "prj_code": 12345,
    "survey_link": "http://test.com/id/XXXXX",
    "criteriaRequest": [
        {
            "name": "gender",
            "value": ["female"]
        },
        {
            "name": "age",
            "value": ["20","25"]
        }
    ]
}
  • Response Parameters
    • Parameters
      • `prj_code`Survey Created For Project Id.
      • `survey_link`Survey Link
      • `criteriaRequest`Criteria to identify panlist who qualifies to take survey.
Change Survey Status
Survey Status Endpoint

/v1/prodigious/survey/status

Request
  • Method `post`
  • Headers
    • `Content-Type: application/json`
    • `Authorization: Bearer YOUR_ACCESS_TOKEN`
  • Body
    {
        "prj_code": 12345,
        "status": "Active"
    }
  • Parameters
    • `prj_code`(Required Integer): Unique Project Id recived when created project.
    • `status`(Required String): Active and Inactive are accepted values to change survey status for launching and closing survey
Response
{
    "prj_code": 12345,
    "status": "Active"
}
  • Response Parameters
    • `prj_code`Status changed for Project Id.
    • `status`Current Status
Finish Survey Postback Url
Finish Survey Endpoint

/v1/prodigious/end/survey

Request
  • Method `post`
  • Headers
    • `Content-Type: application/json`
    • `Authorization: Bearer YOUR_ACCESS_TOKEN`
  • Body
    {
        "id": 12345,
        "status": "Complete"
    }
  • Parameters
    • `id`(Required Integer): Unique survey id passed while taking survey.
    • `status`(Required String): Complete, Terminate, SecurityTerminate and Quota Full are accepted values to mark survey status as Complete, Terminate Or Quota Terminate
Response
{
    "response": 1,
    "message": "Successfully Updated Status to Terminate"
}
  • Response Parameters
    • `response`On Successfully updating survey status response 1 will be passed and 0 if survey status update failed.
    • `status`Message for successful updation of survey status or failing to update survey status
Fetch Survey Data
Fetch Survey Data Endpoint

/v1/prodigious/survey/fetch/data

Request
  • Method `post`
  • Headers
    • `Content-Type: application/json`
    • `Authorization: Bearer YOUR_ACCESS_TOKEN`
  • Body
    {
        "prjCode": 12345,
    }
  • Parametersa
    • `prjCode`(Required Integer): Unique project code to fetch data for.
Response
[
    {
        "prj_code": 3747295156412416,
        "surveyLink": "http://localhost:3000/3977797320187905",
        "unq_id": "3977797320187905",
        "started_on": 1692168939.198953000,
        "ip_address": "127.0.0.1",
        "completed_on": null,
        "status": "Terminated"
    }
]
  • Response Parameters
    • `prj_code`Project id for which data is fetched.
    • `surveyLink`Survey Link used to take survey.
    • `unq_id`Unique Survey Id used to take survey.
    • `started_on`Survey first attempted on date time in millisecond format.
    • `ip_address`Ip address of the user from which survey attempted.
    • `completed_on`Survey completion date time in millisecond format.
    • `status`Current status of survey attempted
Fetch Survey Data For Single Repondent
Fetch Survey Data Endpoint For Single Respondent

/v1/prodigious/survey/search/data

Request
  • Method `post`
  • Headers
    • `Content-Type: application/json`
    • `Authorization: Bearer YOUR_ACCESS_TOKEN`
  • Body
    {
        "id": 12345,
    }
  • Parametersa
    • `id`(Required String): Unique respondent id used to take survey.
Response
{
    "prj_code": 3747295156412416,
    "surveyLink": "http://localhost:3000/3977797320187905",
    "unq_id": "3977797320187905",
    "started_on": 1692168939.198953000,
    "ip_address": "127.0.0.1",
    "completed_on": null,
    "status": "Terminated"
}
  • Response Parameters
    • `prj_code`Project id for which data is fetched.
    • `surveyLink`Survey Link used to take survey.
    • `unq_id`Unique Survey Id used to take survey.
    • `started_on`Survey first attempted on date time in millisecond format.
    • `ip_address`Ip address of the user from which survey attempted.
    • `completed_on`Survey completion date time in millisecond format.
    • `status`Current status of survey attempted