Client API

Introduction Get Question Library Get Question Options Get Question Options Library Get Project List Get Project Detail Create Project Update Project Update Project Status Post Targeting Get Targeting Get Redirect Links Hashing Mechanism

Client API

Introduction:

The following are the base URLs for the Client API.

Base URL

Environment URL
PROD https://api.imadconnect.com/
Staging https://st-api.imadconnect.com/

Staging is a sandbox environment that can be used for testing. You will need credentials to access it. Credentials can be requested by contacting your integration contact.

In this documentation, the base URL will appear as the variable {baseUrl}.

Client API

Get Question Library:

This API will allow client to get all Questions for specific country language.

Question List can be retrived for any specific language code and country code combination.

Query Parameters

Property Type Required Description
CountryCode string Yes Question list based on country selected
LangCode string Yes Question list based on language selected

Please download the reference CountryCode master file. Download

Please download the reference LanguageCode master file. Download

Location Request

GET '{baseUrl}/v1.0/Client/GetQuestionLibrary?langCode=EN&countryCode=US' \ --header 'x-api-key: Client Secret Key'


Type

"Type" : GET,


Example Response

[
{
"questionId" : 3443,
"questionTitle" : "AGE",
"controlType" : "Radio",
"questionDesc" : "What is your age?",
"languageCode" : "EN",
"countryCode" : "US",
},
{
"questionId" : 3444,
"questionTitle" : "ALCOHOL_FREQUENCY",
"controlType" : "Radio",
"questionDesc" : "On average, how many alcoholic drinks do you consume in a week?",
"languageCode" : "EN",
"countryCode" : "US",
},
{
"questionId" : 3445,
"questionTitle" : "AUTO_BRANDS",
"controlType" : "Radio",
"questionDesc" : "If you own/lease a car(s), which brand(s) are they?",
"languageCode" : "EN",
"countryCode" : "US",
},
{
"questionId" : 3446,
"questionTitle" : "AUTO_DECISION_MAKER",
"controlType" : "Radio",
"questionDesc" : "Are you the primary decision maker in your household for automotive-related purchases?",
"languageCode" : "EN",
"countryCode" : "US",
},
{
"questionId" : 3447,
"questionTitle" : "AUTO_FUTURE_PURCHASE_20",
"controlType" : "Radio",
"questionDesc" : "When do you estimate that you will purchase/lease your next car?",
"languageCode" : "EN",
"countryCode" : "US",
},
{
"questionId" : 3448,
"questionTitle" : "AUTO_MANUFACTURE_DATE",
"controlType" : "Radio",
"questionDesc" : "What year was your main vehicle (owned or leased) manufactured?",
"languageCode" : "EN",
"countryCode" : "US",
},
]

Client API

Get Question Options:

This API will allow client to get all Question Options for specific question.

Location Request

GET '{baseUrl}/v1.0/Client/GetQuestionOptions?id=3465' \ --header 'x-api-key: Client Secret Key'


Type

"Type" : GET,


Example Response

[
{
"optionId" : 52116,
"questionId" : 3465,
"optionText" : "Administration/General Staff",
"order" : 0,
"languageCode" : "EN",
},
{
"optionId" : 52117,
"questionId" : 3465,
"optionText" : "Customer Service/Client Service",
"order" : 0,
"languageCode" : "EN",
},
{
"optionId" : 52118,
"questionId" : 3465,
"optionText" : "Executive Leadership",
"order" : 0,
"languageCode" : "EN",
},
{
"optionId" : 52119,
"questionId" : 3465,
"optionText" : "Finance/Accounting",
"order" : 0,
"languageCode" : "EN",
},
{
"optionId" : 52120,
"questionId" : 3465,
"optionText" : "Human Resources",
"order" : 0,
"languageCode" : "EN",
},
]

Client API

Get Question Option Library:

This API will allow client to get all Questions for specific country language.

Question List can be retrived for any specific language code and country code combination.

Query Parameters

Property Type Required Description
CountryCode string Yes Question list based on country selected
LangCode string Yes Question list based on language selected

Please download the reference CountryCode master file. Download

Please download the reference LanguageCode master file. Download

Location Request

GET '{baseUrl}/v1.0/Client/GetQuestionOptionLibrary?langCode=EN&countryCode=US' \ --header 'x-api-key: Client Secret Key'


Type

"Type" : GET,


Example Response

[
{
"questionId" : 3443,
"questionTitle" : "Gender",
"controlType" : "Radio",
"questionDesc" : "What is your gender?",
"languageCode" : "EN",
"countryCode" : "US",
"options" : [
                   {
                     "optionId" : 5245,
                     "questionId" : 3443,
                     "optionText" : "Male",
                     "order" : 1,
                     "languageCode" : "EN",
                    },
                   {
                     "optionId" : 5246,
                     "questionId" : 3443,
                     "optionText" : "Female",
                     "order" : 2,
                     "languageCode" : "EN",
                    },
                 ],
 },
]

Client API

Get Project List:

This API will allow client(s) to see all mapped project linked to them.

Definition

GET '{baseUrl}/v1.0/Client/GetProjectList' \ --header 'x-api-key: < Key Provided to you >


Type

"Type" : GET,


Example Response

[
{
"projectId" : 50096,
"projectCode" : "IMR12086",
"projectDescription" : null,
"projectName" : "facebook usage statistics",
"clientName" : null,
"projectFlag" : "1",
"projectType" : S,
"parentProjectId" : null,
"projectCategory" : "Consumer",
"startDate" : null,
"endDate" : null,
"countryName" : "U.S. Virgin Islands ",
"lOI" : null,
"projectCategory" : "Consumer",
"isPreScreen" : "true",
"sampleSize" : "300",
"ir" : "80.00",
"respondentClickQuota" : "600",
"isExclude" : null,
"isMultiLink" : null,
"isReContact" : null,
"isGeoLocation" : null,
"complete" : "10",
"terminate" : "3",
"overQuota" : "1",
"qualityTerm" : "1",
"dropout" : "1",
"lastComplete" : "2021-03-04T11:30:14.843",
"remainingSample" : "990",
"remainingClick" : "-10",
"fieldloi" : "1",
"fieldIR" : null,
"conversion" : "55.56 %",
"dropRate" : "5.56 %",
"cpi" : "1.50",
},

{
"projectId" : 50098,
"projectCode" : "IMR12098",
"projectDescription" : null,
"projectName" : "Social media statistics",
"clientName" : null,
"projectFlag" : "1",
"projectType" : S,
"parentProjectId" : null,
"projectCategory" : "Consumer",
"startDate" : null,
"endDate" : null,
"countryName" : "U.S. Virgin Islands ",
"lOI" : null,
"projectCategory" : "Consumer",
"isPreScreen" : "true",
"sampleSize" : "300",
"ir" : "80.00",
"respondentClickQuota" : "600",
"isExclude" : null,
"isMultiLink" : null,
"isReContact" : null,
"isGeoLocation" : null,
"complete" : "10",
"terminate" : "3",
"overQuota" : "1",
"qualityTerm" : "1",
"dropout" : "1",
"lastComplete" : "2021-03-04T11:30:14.843",
"remainingSample" : "990",
"remainingClick" : "-10",
"fieldloi" : "1",
"fieldIR" : null,
"conversion" : "55.56 %",
"dropRate" : "5.56 %",
"cpi" : "1.50",
},

{
"projectId" : 50098,
"parentProjectId" : null,
"projectType" : S,
"projectCode" : "IMR12086",
"projectName" : "facebook usage statistics",
"projectCategory" : "Consumer",
"clientName" : null,
"startDate" : null,
"endDate" : null,
"lastComplete" : "2021-03-04T11:30:14.843",
"cpi" : "1.50",
"respondentClickQuota" : null,
"remainingClick" : "-10",
"fieldloi" : "1",
"fieldIR" : null,
"isPreScreen" : "true",
"isMultiLink" : null,
"isReContact" : null,
"isExclude" : null,
"sampleSize" : null,
"projectDescription" : null,
"isActive" : null,
"remainingSample" : "990",
"complete" : "10",
"terminate" : "3",
"overQuota" : "1",
"dropout" : "1",
"lOI" : null,
"iR" : "61.11 %",
"conversion" : "55.56 %",
"dropRate" : "5.56 %",
"projectStats" : "1"
},

]

Client API

Get Project Details:

This API will allow client(s) to get the project details for the particular mapped project.

Query Parameters

Property Type Required Description
ProjectId Integer Yes Project Id of particular Project (like: 50228)

Location Request

GET '{baseUrl}/v1.0/Client/GetProjectDetails?ProjectId=50228' \ --header 'x-api-key: Key Provided to you'


Type

"Type" : GET,


Example Response

{
"projectId" : 50096,
"projectCode" : "IMR12086",
"projectName" : "facebook usage statistics", "projectDescription" : "Facebook Demographic Statistics: How Many population uses Facebook every month",
"countryName" : "India",
"countryCode" : "IN",
"loi" : "4",
"sampleSize" : 1000,
"startDate" : "2021-03-04T00:00:00",
"endDate" : "2021-03-31T00:00:00",
"ir" : "80.00",
"respondentClickQuota" : "0",
"projectCPI" : "0",
"singleLinkUrl" : "https://st-redirect.imadconnect.com/TestSurvey/Index?uid=[identifier]",
"singleLinkUrlTest" : "https://st-redirect.imadconnect.com/TestSurvey/Index?uid=[identifier]&test=1",
"isPreScreen" : "true",
"isDynamicThanksUrl" : "false",
"isCollectPII" : "false",
"isExclude" : "false",
"isReContact" : null,
"isMultiLinkUrl" : "false",
"isMobile" : "true",
"isTablet" : "true",
"isDesktop" : "true",
"projectFlag" : 1,
"sid" : "0",
"projectType" : "S",
"languageName" : "English",
"currencyCode" : "USD",
"projectCategory" : "Consumer",

"complete" : "10",
"terminate" : 3,
"overQuota" : 1,
"dropout" : 1,
"lastComplete" : "2021-03-04T11:30:14.843",
"remainingSample" : 990,
"remainingClicks" : null,
"fieldLOI" : 1,
"fieldIR" : "61.11 %",
"conversion" : "55.56 %",
"dropRate" : "5.56 %",
}

Client API

Create Project:

This API will allow client(s) to create projects.

Please download the reference master file for assigning CountryId, LanguageId, CurrencyCode & ProjectCategoryId. Download

Required Body Parameters:

Property Type Required
ProjectName String Yes
CountryCode String Yes
LanguageCode String Yes
ProjectCategoryId Integer Yes
ProjectDescription String No
Loi Decimal Yes
Ir Decimal Yes
SampleSize Integer Yes
RespondentClickQuota Integer Yes
CurrencyCode String Yes
Cpi Decimal Yes
StartDate Date Yes
EndDate Date Yes
SingleLinkUrl String Yes
SingleLinkUrlTest String Yes
IsMobile Bool No (Default value will be true)
IsTablet Bool No (Default value will be true)
IsDesktop Bool No (Default value will be true)

Location Request

POST '{baseUrl}/v1.0/Client/CreateProject' \ --header 'x-api-key: Client Secret Key'


Type

"Type" : POST,


Body

{
"projectName" : "TestClientAPI",
"CountryCode" : "US",
"LanguageCode" : "EN",
"ProjectCategoryId" : 3,
"ProjectDescription" : Test Note,
"Loi" : 1,
"Ir" : 2.36,
"SampleSize" : 100,
"RespondentClickQuota" : 500,
"CurrencyCode" : "2",
"Cpi" : 2.37,
"StartDate" : "2021-04-07",
"EndDate" : "2021-04-22",
"SingleLinkUrl" : "https://st-redirect.imadconnect.com/Navigate?tid=4M9QJMB7&uid=[identifier]",
"SingleLinkUrlTest" : "https://st-redirect.imadconnect.com/Navigate?tid=4M9QJMB7&uid=[identifier]",
"IsMObile" : true,
"IsTablet" : true,
"IsDesktop" : true,
},


Example Response

12086

Client API

Update Project:

This API will allow client(s) to update projects.

Please download the reference master file for assigning CountryId, LanguageId, CurrencyCode & ProjectCategoryId. Download

Query Parameters

Property Type Required Description
ProjectId Integer Yes Project Id of particular Project (like: 50228)

Required Body Parameters:

Property Type Required
ProjectName String Yes
ProjectCategoryId Integer Yes
ProjectDescription String No
Loi Decimal Yes
Ir Decimal Yes
SampleSize Integer Yes
RespondentClickQuota Integer Yes
CurrencyCode String Yes
Cpi Decimal Yes
StartDate Date Yes
EndDate Date Yes
SingleLinkUrl String Yes
SingleLinkUrlTest String Yes
IsMobile Bool No (Default value will be true)
IsTablet Bool No (Default value will be true)
IsDesktop Bool No (Default value will be true)

Location Request

POST '{baseUrl}/v1.0/Client/UpdateProject?ProjectId=******' \ --header 'x-api-key: Client Secret Key'


Type

"Type" : POST,


Body

{
"projectName" : "TestClientAPI",
"ProjectCategoryId" : 3,
"ProjectDescription" : Test Note,
"Loi" : 1,
"Ir" : 2.36,
"SampleSize" : 100,
"RespondentClickQuota" : 500,
"CurrencyCode" : "2",
"Cpi" : 2.37,
"StartDate" : "2021-04-07",
"EndDate" : "2021-04-22",
"SingleLinkUrl" : "https://st-redirect.imadconnect.com/Navigate?tid=4M9QJMB7&uid=[identifier]",
"SingleLinkUrlTest" : "https://st-redirect.imadconnect.com/Navigate?tid=4M9QJMB7&uid=[identifier]",
"IsMObile" : true,
"IsTablet" : true,
"IsDesktop" : true,
},


Example Response

12086

Client API

Update Project Status :

This API will allow client(s) to update project status.

Any Project having status not OnHold can be updated and if try to update OnHold Project status then below error message will be shown.

"Project status can't be updated as its OnHold."

Query Parameters

Property Type Required Description
ProjectId Integer Yes Project Id of particular Project (like: 50228)
FlagId Integer Yes FlagId of particular Project

Refer following table of FlagIds for updating Project

FlagStatus FlagId
Active 1
InActive 2
OnHold 3
Closed 4
Invoiced 5

Location Request

POST '{baseUrl}/v1.0/Client/UpdateProjectStatus?ProjectId=****&FlagId=*' \ --header 'x-api-key: Client Secret Key'


Type

"Type" : POST,



Example Response

Project status updated successfully.

Client API

Post Targeting:

This API will allow client(s) to post targeting.

Query Parameters

Property Type Required Description
ProjectId Integer Yes Project Id of particular Project (like: 50228)

Location Request

POST '{baseUrl}/v1.0/Client/PostTargeting?ProjectId=******' \ --header 'x-api-key: Client Secret Key'


Type

"Type" : POST,


Body

{
"Questions" :[
   {
     "QuestionId" : 60002,
     "Options" : [
       300001,
       300002
     ]
   },
   {
     "QuestionId" : 60001,
     "Ages" : [
       "From":10,
       "To":50
     ]
   },
   {
     "QuestionId" : 4039,
     "ZipCodes" : [
       123456,
       654321
     ]
   },
]
}


Example Response

{True}

Client API

Get Targeting:

This API will allow client(s) to get targeting.

Query Parameters

Property Type Required Description
ProjectId Integer Yes Project Id of particular Project (like: 50228)

Location Request

GET '{baseUrl}/v1.0/Client/GetTargeting?ProjectId=50228' \ --header 'x-api-key: Key Provided to you'


Type

"Type" : GET,


Example Response

{
[
   {
     "QuestionId" : 60002,
     "Options" : [
       300001,
       300002
     ]
   },
   {
     "QuestionId" : 60001,
     "Ages" : [
       "From":10,
       "To":50
     ]
   },
   {
     "QuestionId" : 4039,
     "ZipCodes" : [
       123456,
       654321
     ]
   },
]
}

Client API

Get Redirect Links:

This API will allow client to get their Redirect Links for specific project.

Query Parameters

Property Type Required Description
ProjectId Integer Yes Project Id of particular Project (like: 50228)

Location Request

GET '{baseUrl}/v1.0/Client/GetRedirectLinks?ProjectId=*****' \ --header 'x-api-key: Client Secret Key'


Type

"Type" : GET,


Example Response

{
"RedirectComplete" : "https://st-redirect.imadconnect.com/Thanks/Index?status=c&uid=[identifier]",
"RedirectTerminate" : "https://st-redirect.imadconnect.com/Thanks/Index?status=t&uid=[identifier]",
"RedirectOverquota" : "https://st-redirect.imadconnect.com/Thanks/Index?status=q&uid=[identifier]",
"RedirectQualityTerm" : "https://st-redirect.imadconnect.com/Thanks/Index?status=f&uid=[identifier]",
"RedirectSurveyClose" : "https://st-redirect.imadconnect.com/Thanks/Index?status=sc&uid=[identifier]",
},

Client API

Hashing Mechanism : Redirect URL for complete

imadconnect uses Hashing Mechanism for the encryption using SHA1 Encryption.

Steps to generate hash -
  1. Secret key, is required to generate hash, and will be provided by imadconnect Manager. For eg. 9S9z4T9K6hyqEMlkoATOpZFZpLT5Urgc
  2. imadconnect will use complete URL without hash variable in it. For eg.

    https://st-redirect.imadconnect.com/thanks/index?status=c&uid=4E53F51A-632D-4CC4-889E-EEED30A0673E

Sample C# code to generate hash :

public static string HashString(string StringToHash, string HachKey)
{
System.Text.UTF8Encoding myEncoder = new System.Text.UTF8Encoding();
byte[ ] Key = myEncoder.GetBytes(HachKey);
byte[ ] Text = myEncoder.GetBytes(StringToHash);
System.Security.Cryptography.HMACSHA1 myHMACSHA1 = new
System.Security.Cryptography.HMACSHA1(Key);
byte[ ] HashCode = myHMACSHA1.ComputeHash(Text);
string hash = BitConverter.ToString(HashCode).Replace("-", "");
return hash.ToLower();
}

Generated Hash = “6c8e890b31f489780a3796e02f64c4551ec85eb1”. Add this hash value in the URL mentioned in step 2.

Final URL which will be redirected as below:

https://st-redirect.imadconnect.com/thanks/index?status=c&uid=4E53F51A-632D-4CC4-889E-EEED30A0673E&conhash= 6c8e890b31f489780a3796e02f64c4551ec85eb1