Start a survey

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Start&key={KEY}&surveyId={SURVEYID}

true

Stop a survey

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Stop&key={KEY}&surveyId={SURVEYID}

true

Copy a survey

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Copy&key={KEY}&surveyId={SURVEYID}

1

Delete a survey

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Delete&key={KEY}&surveyId={SURVEYID}

true

Get a listing of surveys

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_List&key={KEY}

{
    "1": {
        "surveyId": "1",
        "name": "My Survey",
        "title": "",
        "status": "active",
        "type": "survey",
        "startDate": "0000-00-00 00:00:00",
        "endDate": "0000-00-00 00:00:00",
        "surveyURL": "https:\/\/s.vagrant.surveytown.com\/survey\/?c=5967&id=1",
        "urlVariables": [
            {
                "name": "MyUrlVariable",
                "label": "",
                "default": ""
            }
        ],
        "tags": [
            {
                "tagId": "1",
                "name": "My Tag"
            }
        ]
    }
}

Find surveys based on specific criteria
If the 'page' optionalParameter is provided, results are paginated to 1000 surveys per page.

If the 'offset' optionalParameter is provided, the result set will start at that parameter's value (indexed from 0).

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Find&key={KEY}&optionalParameters[surveyId]={SURVEYID}

{
    "1": {
        "surveyId": "1",
        "name": "My Survey",
        "title": "",
        "status": "active",
        "type": "survey",
        "startDate": "0000-00-00 00:00:00",
        "endDate": "0000-00-00 00:00:00",
        "surveyURL": "https:\/\/s.vagrant.surveytown.com\/survey\/?c=5967&id=1",
        "urlVariables": [
            {
                "name": "MyUrlVariable",
                "label": "",
                "default": ""
            }
        ],
        "tags": [
            {
                "tagId": "1",
                "name": "My Tag"
            }
        ]
    }
}

Retrieve a survey

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Get_Info&key={KEY}&surveyId={SURVEYID}

{
    "surveyId": "1",
    "name": "My Survey",
    "type": "survey",
    "status": "active",
    "surveyUrl": "https:\/\/s.vagrant.surveytown.com\/survey\/?c=5967&id=1",
    "closedMessage": "The survey you are looking for is CLOSED and is not accepting responses.",
    "dateLimited": "",
    "startDate": "0000-00-00 00:00:00",
    "endDate": "0000-00-00 00:00:00",
    "title": "",
    "headerImage": "",
    "showQuestionNumber": "",
    "showQuestionNumberType": "",
    "showProgressBar": "",
    "progressBarPages": "",
    "progressBarPercentage": "",
    "progressBarPosition": "",
    "showIntro": "",
    "introText": "",
    "thanksType": "default",
    "thanksMessage": "Thanks for taking this survey.",
    "thanksUrl": "",
    "surveyTemplateId": "",
    "ipLimited": "",
    "ipLimitedType": "",
    "purlLimited": "",
    "responseLimit": "",
    "sendConfirmationEmail": "",
    "confirmationEmailTo": "",
    "confirmationEmailSubject": "",
    "confirmationEmailHtml": "",
    "sendNotifyEmail": "",
    "notifyEmailTo": "",
    "notifyEmailSubject": "",
    "notifyEmailHtml": "",
    "urlVariables": [
        {
            "name": "MyUrlVariable",
            "label": "",
            "default": ""
        }
    ],
    "tags": [
        {
            "tagId": "1",
            "name": "My Tag"
        }
    ],
    "createdDate": "2019-09-03 18:43:47",
    "updatedDate": "2019-09-04 01:55:48",
    "pages": [
        {
            "pageId": "2",
            "displayOrder": "1",
            "questions": [
                {
                    "questionId": "1",
                    "questionType": "netPromoter",
                    "displayOrder": "1",
                    "questionText": "<p>How likely are you to recommend ACME to a friend or colleague?<\/p>",
                    "token": "",
                    "isRequired": "",
                    "canDelete": "1",
                    "canCopy": "1"
                }
            ],
            "logic": [
                {
                    "logicId": "1",
                    "conditions": [
                        {
                            "questionId": "1",
                            "conditionType": "isLessThan",
                            "conditionValue": "5"
                        }
                    ],
                    "action": {
                        "matchType": "any",
                        "pageAction": "goToUrl",
                        "submitSurveyGoToUrl": "https:\/\/acme.com\/help",
                        "goToUrl": "",
                        "jumpPageId": "0",
                        "sendEmail": "",
                        "emailSubject": "",
                        "emailHtml": "",
                        "emailText": "",
                        "emailToAddress": "",
                        "alertEmailAddress": [
                            ""
                        ]
                    }
                }
            ]
        }
    ]
}

Retrieves the questions for a particular survey

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Get_Questions&key={KEY}&surveyId={SURVEYID}

{
    "1": {
        "questionId": "1",
        "questionType": "netPromoter",
        "pageId": "2",
        "displayOrder": "1",
        "questionText": "<p>How likely are you to recommend ACME to a friend or colleague?<\/p>",
        "token": "",
        "isRequired": "",
        "canDelete": "1",
        "canCopy": "1"
    }
}

Counts how many responses a survey has.

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Get_Response_Count&key={KEY}&surveyId={SURVEYID}

1

Retrieve responses a specific contact has entered

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Get_Responses_By_Email&key={KEY}&emailAddress={EMAILADDRESS}&optionalParameters[surveyId]={SURVEYID}

{
    "1": [
        {
            "responseId": "1",
            "ipAddress": "UNKNOWN",
            "responseStart": "2019-09-03 18:44:52",
            "responseComplete": "2019-09-03 18:44:53",
            "isComplete": "1",
            "contactId": "1",
            "contactEmail": "[email protected]",
            "personCode": "",
            "1": {
                "response": {
                    "choiceId": "",
                    "responseValue": "10"
                },
                "questionText": "<p>How likely are you to recommend ACME to a friend or colleague?<\/p>",
                "questionId": "1",
                "questionTypeId": "15",
                "questionType": "netPromoter",
                "token": "",
                "isRequired": ""
            },
            "urlVariables": {
                "myurlvariable": {
                    "name": "myurlvariable",
                    "label": "myurlvariable",
                    "value": ""
                }
            }
        }
    ]
}

Retrieve responses for a specific survey
If the 'page' optionalParameter is provided, results are paginated to 1000 surveys per page.

If the 'offset' optionalParameter is provided, the result set will start at that parameter's value (indexed from 0).

The return value is an array of responses. Each response has array keys for the question ID the response goes with.

The format for a simple textbox question's response looks like this example:

"24": {
"response": {
"choiceId": null,
"responseValue": "A Developer"
},
"questionText": "Who are you? - keep it to one line please.",
"questionId": 24,
"questionType": "singleText",
"token": null,
"isRequired": false
}

Any question that can have only one response will have an array key named "response". Questions that can have more than one response value do /not/ have a "response" key; instead, they have a "responses" key, as seen in this example:

"29": {
"responses": [
{
"choiceId": 98,
"choiceText": "Blake",
"responseValue": 6
},
{
"choiceId": 99,
"choiceText": "Brian",
"responseValue": 5
},
],
"questionText": "What number is each person thinking of? (remember, their numbers, and therefore also your guesses, must sum to 1001)",
"questionId": 29,
"questionType": "addSum",
"token": null,
"isRequired": false
}

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Get_Responses&key={KEY}&surveyId={SURVEYID}&optionalParameters[startDate]={STARTDATE}

[
    {
        "responseId": "1",
        "ipAddress": "UNKNOWN",
        "responseStart": "2019-09-03 18:44:52",
        "responseComplete": "2019-09-03 18:44:53",
        "isComplete": "1",
        "contactId": "1",
        "contactEmail": "[email protected]",
        "personCode": "",
        "1": {
            "response": {
                "choiceId": "",
                "responseValue": "10"
            },
            "questionText": "<p>How likely are you to recommend ACME to a friend or colleague?<\/p>",
            "questionId": "1",
            "questionTypeId": "15",
            "questionType": "netPromoter",
            "token": "",
            "isRequired": ""
        },
        "urlVariables": {
            "myurlvariable": {
                "name": "myurlvariable",
                "label": "myurlvariable",
                "value": ""
            }
        }
    }
]

Add a tag to a survey

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Add_Tag&key={KEY}&surveyId={SURVEYID}&tagId={TAGID}

true

Remove a tag from a survey

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Survey_Remove_Tag&key={KEY}&surveyId={SURVEYID}&tagId={TAGID}

true

Create a new tag

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Tag_Create&key={KEY}&name={NAME}

1

Update an existing Tag

Update Parameters can include:
- name: The name of your tag

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Tag_Update&key={KEY}&tagId={TAGID}

true

Delete a tag you created

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Tag_Delete&key={KEY}&tagId={TAGID}

true

Get a listing of tags

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Tag_List&key={KEY}&optionalParameters[sortBy]={SORTBY}

[
    {
        "tagId": "1",
        "name": "My Tag"
    }
]

Retrieve a survey response

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Response_Get&key={KEY}&surveyId={SURVEYID}&responseId={RESPONSEID}

{
    "responseId": "1",
    "ipAddress": "UNKNOWN",
    "responseStart": "2019-09-03 18:44:52",
    "responseComplete": "2019-09-03 18:44:53",
    "isComplete": "1",
    "contactId": "1",
    "contactEmail": "[email protected]",
    "personCode": "",
    "1": {
        "response": {
            "choiceId": "",
            "responseValue": "10"
        },
        "questionText": "<p>How likely are you to recommend ACME to a friend or colleague?<\/p>",
        "questionId": "1",
        "questionTypeId": "15",
        "questionType": "netPromoter",
        "token": "",
        "isRequired": ""
    },
    "urlVariables": {
        "myurlvariable": {
            "name": "myurlvariable",
            "label": "myurlvariable",
            "value": ""
        }
    }
}

Create a survey response

updateparam singleText
updateparam multiText
- updateParameters[{QuestionID}]=string
- updateParameters[13]=steve

updateparam singleChoice
updateparam multiChoice
- updateParameters[{QuestionID}][{ChoiceID}]=bool
- updateParameters[16][44]=1
- updateParameters[16][45]=1

updateparam addSum
updateparam ranker
- updateParameters[{QuestionID}][{ChoiceID}]=int
- updateParameters[18][59]=20
- updateParameters[18][60]=80

updateparam matrix
- updateParameters[{QuestionID}][{OptionID}][{ChoiceID}]=bool
- updateParameters[17][5][54]=1
- updateParameters[17][7][56]=1

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Response_Create&key={KEY}&surveyId={SURVEYID}&optionalParameters[isComplete]={ISCOMPLETE}

1

Update an existing survey response

updateparam singleText
updateparam multiText
- updateParameters[{QuestionID}]=string
- updateParameters[13]=steve

updateparam singleChoice
updateparam multiChoice
- updateParameters[{QuestionID}][{ChoiceID}]=bool
- updateParameters[16][44]=1
- updateParameters[16][45]=1

updateparam addSum
updateparam ranker
- updateParameters[{QuestionID}][{ChoiceID}]=int
- updateParameters[18][59]=20
- updateParameters[18][60]=80

updateparam matrix
- updateParameters[{QuestionID}][{OptionID}][{ChoiceID}]=bool
- updateParameters[17][5][54]=1
- updateParameters[17][7][56]=1

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Response_Update&key={KEY}&surveyId={SURVEYID}&responseId={RESPONSEID}&optionalParameters[isComplete]={ISCOMPLETE}

1

Delete a response from a survey

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Response_Delete&key={KEY}&surveyId={SURVEYID}&responseId={RESPONSEID}

true

Subscribe a contact to a survey

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Contact_Subscribe&key={KEY}&surveyId={SURVEYID}&channel={CHANNEL}&contact[email]={EMAIL}&optionalParameters[sendAt]={SENDAT}

true

Unsubscribe a contact from a survey

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Contact_Unsubscribe&key={KEY}&surveyId={SURVEYID}&id={ID}

true

Delete a contact

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Contact_Delete&key={KEY}&id={ID}

true

Integrate into your own web application by setting your SURVEYS_SSO_COOKIE

Please contact support for details, this function is only available to reseller accounts

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Integration_Get_Cookie&key={KEY}&clientId={CLIENTID}&username={USERNAME}&time={TIME}

mWSMis/dof9BEMUQj2u7+qemcQ6XpjhupzKmhYuy+ikLpA/uOQS1Z5KmlrRvAsSOrLZG0R4/SVWp2Hh3r4IYbZt9p7nPNu60Gw==|FOdkZ7qTYL4=|KnNEO3MmMTU5NjhJXmtkZjg5

Integrate into your own web application by setting your SURVEYS_SSO_COOKIE using your client's credentials

Please contact support for details, this function is only available to reseller accounts

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Integration_Login_Get_Cookie&key={KEY}&username={USERNAME}&password={PASSWORD}&time={TIME}

{
    "clientId": "5968",
    "username": "resellersub",
    "cookie": "ll3gr3CKyP7Aal\/wLpXsT8iXTyQKrWwZAQ2EZcqf9Ow7Is\/J07IpQwUo0eGIZQIwcIKC4GvDAO35S0MaD0O2JSmbOGH0f02q6Q==|xEbhY0GDLy4=|KnNEO3MmMTU5NjhJXmtkZjg5"
}

Create a new account with the given parameters

Please contact support for details, this function is only available to reseller accounts

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Create_Account&key={KEY}&clientName={CLIENTNAME}&adminEmail={ADMINEMAIL}&userName={USERNAME}&password={PASSWORD}&optionalParameters[clientBusinessName]={CLIENTBUSINESSNAME}

1

Get a list of your current clients

Please contact support for details, this function is only available to reseller accounts

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Get_Accounts&key={KEY}

{
    "5968": "Reseller Subaccount"
}

Get a list of your clients based on parameters

Please contact support for details, this function is only available to reseller accounts

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Find_Accounts&key={KEY}&optionalParameters[createDateStart]={CREATEDATESTART}

[
    {
        "clientId": "5968",
        "clientStatus": "active",
        "clientCreated": "2019-10-29 18:12:00"
    }
]

Modify an existing account with the given parameters

Please contact support for details, this function is only available to reseller accounts

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Update_Account&key={KEY}&clientId={CLIENTID}&optionalParameters[clientName]={CLIENTNAME}

1

Suspend an Account you created

Please contact support for details, this function is only available to reseller accounts

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Suspend_Account&key={KEY}&clientId={CLIENTID}

true

Reinstate an Account you suspended

Please contact support for details, this function is only available to reseller accounts

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Reinstate_Account&key={KEY}&clientId={CLIENTID}

true

Creates an API key for the specified account.

Please contact support for details, this function is only available to reseller accounts

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Create_Account_Key&key={KEY}&clientId={CLIENTID}&optionalParameters[username]={USERNAME}

002b24a00bf4327bd5b28b9e954eb089

Return the API key for an account, or create one if one doesn't already exist and the username is not specified.

Please contact support for details, this function is only available to reseller accounts

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Get_Account_Key&key={KEY}&clientId={CLIENTID}&optionalParameters[userName]={USERNAME}

002b24a00bf4327bd5b28b9e954eb089

Send an Alert Message to a set of your clients

Please contact support for details, this function is only available to reseller accounts

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Send_Message&key={KEY}&clientIds[]={CLIENTIDS}&shortMessage={SHORTMESSAGE}&optionalParameters[fullMessage]={FULLMESSAGE}

true

Get the current Webhooks settings for the specified Account

Please contact support for details, this function is only available to reseller accounts

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Get_Account_Webhooks&key={KEY}&clientId={CLIENTID}

{
    "url": "https:\/\/acme.com\/endpoint",
    "webhooksKey": "amazinglysecurekey",
    "hooks": [

    ],
    "locations": [
        "System"
    ],
    "customFieldIds": [
        "1",
        "2"
    ]
}

Admin_Set_Account_Webhooks allows you to set the Webhooks information for the specified Account

Please contact support for details, this function is only available to reseller accounts

The Account's current settings will be overriden, so specify all the hooks and locations you want

Note: To receive WEBHOOK_BOUNCED or WEBHOOK_CLICKED, you must have the System location active

Parameters

Optional Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Set_Account_Webhooks&key={KEY}&clientId={CLIENTID}&url={URL}&webhooksKey={WEBHOOKSKEY}&hooks[]={HOOKS}&locations[]={LOCATIONS}&customFieldIds[]={CUSTOMFIELDIDS}&optionalParameters[bulk]={BULK}

true

Deactivate all Webhooks for an account

Please contact support for details, this function is only available to reseller accounts

Note: Webhooks already queued for sending will still be sent

Parameters

Returns

Example

https://api.givemyresponse.com/2/REST/?method=Admin_Deactivate_Account_Webhooks&key={KEY}&clientId={CLIENTID}

true

Speed up your integration! Our zip file includes functions for our API calls in the following languages:

• PHP
• Python
• Ruby
• Java
• Perl
• C#
• .NET

Download API Wrapper (v2.6.0)