API Documentation

Start a survey

Parameters

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to start

Returns

Type Description
bool Returns true on success

Example

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

Stop a survey

Parameters

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to stop

Returns

Type Description
bool Returns true on success

Example

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

Copy a survey

Parameters

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to copy

Returns

Type Description
int Returns The ID of the new survey

Example

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

Delete a survey

Parameters

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to delete

Returns

Type Description
bool Returns true on success

Example

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

Get a listing of surveys

Parameters

Name Type Optional Description
key string No Your API key - used to authenticate your account

Returns

Type Description
struct Array of surveys with the key of surveyId

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
optionalParameters struct Yes A struct of optional parameters, any combination of which can be used

Optional Parameters

Name Type Description
surveyId int Return only the survey with the supplied ID
status word Return only surveys matching this status. Must be one of "draft", "active", or "complete".
type word Return only surveys matching this type. Must be one of "survey" or "event".
tagId int Return only surveys having this tag ID
startDate date Return only surveys started on this date (UTC)
endDate date Return only surveys ending on this date (UTC)
page int Return surveys on this page of the search results
offset int Starting index to return results from. Indexed from 0.
num int Number of results to return

Returns

Type Description
struct Array of surveys with the key of surveyId and values of name, title, status, start_date, and end_date, ordered by survey ID ascending

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to retrieve

Returns

Type Description
struct Survey properties including questions, logic & actions

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to retrieve the questions for

Returns

Type Description
struct Array of survey questions, with the key of the question ID. The response format is similar to that of Survey_Get_Responses.

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No ID of the survey you want to retrieve the response counts for

Returns

Type Description
int Count of how many responses there are for the given survey

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
emailAddress string No The email address of the contact you want to retrieve responses for
optionalParameters struct Yes A struct of optional parameters, any combination of which can be used

Optional Parameters

Name Type Description
surveyId int Return only survey responses for this survey
startDate date Return only survey responses started on this date (UTC)
endDate date Return only survey responses completed on this date (UTC)
is_complete bool Return only survey responses that are complete (true) or incomplete (false)
page int Return questions on this page of the search results
offset int Starting index to return results from. Indexed from 0.
num int Number of results to return
response_id int Unique response identifier
sortDir string Sort direction, valid values: U, D

Returns

Type Description
struct Array of responses. See Survey_Get_Responses for response format documentation.

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to retrieve the questions for
optionalParameters struct Yes A struct of optional parameters, any combination of which can be used

Optional Parameters

Name Type Description
startDate date Return only survey responses started on this date (UTC)
endDate date Return only survey responses completed on this date (UTC)
completeDate date Return only survey responses completed on or after this date (UTC)
is_complete bool Return only survey responses that are complete (true) or incomplete (false)
page int Return questions on this page of the search results
offset int Starting index to return results from. Indexed from 0.
num int Number of results to return
response_id int Unique response identifier
contact_id int Unique respondent indentifier created
person_code string Unique respondent indentifier provided
sortDir string Sort direction, valid values: U, D. Defaults to D.

Returns

Type Description
struct Array of surveys

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want the tag added to
tagId int No The ID of the tag you want to add

Returns

Type Description
bool Returns true on success

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want the tag removed from
tagId int No The ID of the tag you want to remove

Returns

Type Description
bool Returns true on success

Example

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

Create a new tag

Parameters

Name Type Optional Description
key string No Your API key - used to authenticate your account
name string No The name of your tag

Returns

Type Description
int id Returns the Tag ID of your new tag

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
tagId int No The tagId of the tag you want to modify
updateParameters struct No A struct of replacement values for your tag - only specify items that you want to change

Returns

Type Description
bool Returns true on success

Example

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

Delete a tag you created

Parameters

Name Type Optional Description
key string No Your API key - used to authenticate your account
tagId int No The Tag ID of the tag you wish to delete

Returns

Type Description
bool Returns true on success

Example

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

Get a listing of tags

Parameters

Name Type Optional Description
key string No Your API key - used to authenticate your account
optionalParameters struct Yes A struct of optional parameters, see below for valid keys

Optional Parameters

Name Type Description
sortBy string Field to sort by, value values: name, id
sortDir string Sort direction, valid values: U, D
offset int The number of records to skip (specify a starting point)
num int The maximum number of records to return

Returns

Type Description
struct Array of records with the key of tagId and values of tagId, name

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to retrieve the response from
responseId int No The ID of the response you want to retrieve

Returns

Type Description
struct Array of response properties

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to respond to
updateParameters struct No A struct of update parameters, any combination of which can be used
optionalParameters struct Yes A struct of optional parameters, see below for valid keys

Optional Parameters

Name Type Description
isComplete bool Set a response as completed
personCode string A unique respondent identifier
urlVariables struct A struct of URL Variables: {name=>value}

Returns

Type Description
int Returns responseId on success

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to update the response of
responseId int No The ID of the response you want to update
updateParameters struct No A struct of update parameters, any combination of which can be used
optionalParameters struct Yes A struct of optional parameters, see below for valid keys

Optional Parameters

Name Type Description
isComplete bool Set a response as completed
personCode string A unique respondent identifier
urlVariables struct A struct of URL Variables: {name=>value}

Returns

Type Description
int Returns responseId on success

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The ID of the survey you want to delete from
responseId int No The ID of the response you want to delete

Returns

Type Description
bool Returns true on success

Example

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

Subscribe a contact to a survey

Parameters

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The survey id
channel string No Survey channel. Valid values: email
contact struct No A struct containing contact data


Contact is a struct, which can contain:
- email => value (required if channel is email)
- name => value (optional)
- replacements => struct (optional)
- customFieldToken => value (optional)
- customFieldId => value (optional)

A contact must have a valid email

Ex:
contact = {'email':'[email protected]', 'name': 'Test', 'replacements': {'product_id':'5238', 'purchase_total': '$19.99', 'nickname':'Steve'} }
contact = {'email':'[email protected]', '1':'Support', '2':'User'}
contact = {'email':'[email protected]', '1':'Help', '2':'User', replacements: {'product_id':'4923', 'purchase_total': '$49.99', 'nickname':'Sally'} }

optionalParameters struct Yes A struct of optional parameters, see below for valid keys

Optional Parameters

Name Type Description
sendAt datetime Send the message around a specific datetime (UTC). Will send at the next opportunity by default.
sendDelay int Send the message after waiting a specified number of seconds. Overrides sendAt if both are provided.
filterSubscribed bool Filter out contacts who are already subscribed to the survey - defaults to true

Returns

Type Description
bool Returns true on success

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
surveyId int No The survey id
id string No The identifier of the contact to unsubscribe. Must be an Email.

Returns

Type Description
bool Returns true on success

Example

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

Delete a contact

Parameters

Name Type Optional Description
key string No Your API key - used to authenticate your account
id string No The identifier of the contact to unsubscribe. Must be an Email.

Returns

Type Description
bool True if delete was successful

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientId int No The client ID you are creating the cookie for, must be a client belonging to your reseller account
username string No The username belonging to the client ID you are logging in with the cookie
time int Yes Cookie timeout in seconds

Returns

Type Description
string Cookie value to be set in SURVEYS_SSO_COOKIE

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
username string No The username of the client
password string No The current password of the client
time int Yes Cookie timeout in seconds

Returns

Type Description
struct Returns a struct on a valid username/password combo
Struct Key Type Description
clientId string The clientId belonging to the username given
username string The username that was given as a login
cookie string Cookie value to be set in SURVEYS_SSO_COOKIE

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientName string No Name for the account
adminEmail string No Default email address for the account
userName string No User name for the new account - must be unique and no more than 64 characters
password string No Password for the new account
optionalParameters struct Yes A struct of optional parameters, see below for valid keys

Optional Parameters

Name Type Description
clientBusinessName string The client's Business name, defaults to provided clientName
clientAddr1 string Physical address for the account - will be included in the footer of messages
clientAddr2 string Client's Street Address Line 2 - will be included in the footer of messages
clientCity string Physical address for the account - will be included in the footer of messages
clientState string Physical address for the account - will be included in the footer of messages
clientZip string Physical address for the account - will be included in the footer of messages
phoneNumber string The client's phone number
supportEmail string The client's support email address, defaults to provided adminEmail
clientTimezone string The client's timezone, defaults to UTC
maximumCustomUsers int Maximum custom users
surveyResponseQuota int Maximum people surveyed each month
accountType string Account type, defaults to Professional. Valid values: Basic, Standard, Professional
poweredBy bool Control the display of the "Powered By..." logo, defaults to true
language string The default language the account will have. Valid values are: en, es, fr, ru, it, hr, tr, de, pl, se, fi
numberFormat string The default number format the account will use. Valid values are: us, eu
homePage string URL for the account
logoUrl string URL to the logo image

Returns

Type Description
int The client ID of the new account

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

Name Type Optional Description
key string No Your API key - used to authenticate your account

Returns

Type Description
struct Struct of current client accounts { clientId : clientName, clientId : clientName }

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
optionalParameters struct Yes A struct of optional parameters, see below for valid keys

Optional Parameters

Name Type Description
createDateStart string Return accounts created on or after createDateStart. Format as UTC.
createDateEnd string Return accounts created on or before createDateEnd. Format as UTC.
status string Current account status, valid values: active, disabled.

Returns

Type Description
struct Struct of accounts

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientId int No The client ID number you want to modify
optionalParameters struct No A struct of optional parameters, see below for valid keys

Optional Parameters

Name Type Description
clientName string Name for the account
adminEmail string Default email address for the account
password string Password for the new account
clientBusinessName string The client's Business name, defaults to provided clientName
clientAddr1 string Physical address for the account - will be included in the footer of messages
clientAddr2 string Client's Street Address Line 2 - will be included in the footer of messages
clientCity string Physical address for the account - will be included in the footer of messages
clientState string Physical address for the account - will be included in the footer of messages
clientZip string Physical address for the account - will be included in the footer of messages
phoneNumber string The client's phone number
supportEmail string The client's support email address, defaults to provided adminEmail
clientTimezone string The client's timezone, defaults to UTC
maximumCustomUsers int Maximum Custom Users, defaults to 5
surveyResponseQuota int Maximum people surveyed each month
accountType string Account type, defaults to Basic. Valid values: Basic, Standard, Professional
poweredBy bool Control the display of the "Powered By..." logo, defaults to true
language string The default language the account will have. Valid values are: en, es, fr, ru, it, hr, tr, de, pl, se, fi
numberFormat string The default number format the account will use. Valid values are: us, eu
homePage string URL for the account
logoUrl string URL to the logo image

Returns

Type Description
int The number of fields successfully modified

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientId int No The client ID number you want to modify

Returns

Type Description
bool true on success

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientId int No The client ID number you want to modify

Returns

Type Description
bool true on success

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientId int No The account ID number for which you want the API key
optionalParameters struct Yes A struct of optional parameters, see below for valid keys

Optional Parameters

Name Type Description
username string The username for which you would like the API key. If not specified, the key will be created for the account's default user.

Returns

Type Description
string API Key

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientId int No The account ID number for which you want the API key
optionalParameters struct Yes A struct of optional parameters, see below for valid keys

Optional Parameters

Name Type Description
userName string The username for which you would like the API key

Returns

Type Description
string API Key

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientIds array No An array of Client IDs who will receive the message
shortMessage string No A short message, up to 255 characters
optionalParameters struct Yes A struct of optional parameters, see below for valid keys

Optional Parameters

Name Type Description
fullMessage string The full text of the alert message
url string A URL to include in the alert message
priority int Priority with respect to other alert messages, valid values are 0-5
startDate string Create the message on this date
expiresDate string Create the message on this date
messageId string A unique identifier, maximum of 24 characters

Returns

Type Description
bool True on success

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientId int No The client ID number you want to modify

Returns

Type Description
struct A struct of Webhook data
Struct Key Type Description
url string The URL to receive the Webhook
webhookKey string The Webhook Key passed along with the data to verify the origin
hooks array An array of currently active Webhooks
locations array An array of currently active Webhook Locations
customFieldIds array A list of the Custom Field IDs, indicating what fields will be sent along with contact data when a hook is fired

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientId int No The client ID number you want to modify
url string No The URL to receive the Webhook
webhooksKey string No webhookKey The Webhook Key passed along with the data to verify the origin, this is important for security
hooks array No An array of events you would like to receive Webhooks for. Valid values are: WEBHOOK_SURVEY_CREATED, WEBHOOK_SURVEY_CHANGED, WEBHOOK_SURVEY_DELETED, WEBHOOK_SURVEY_STATUS_CHANGED, WEBHOOK_RESPONSE_CHANGED, WEBHOOK_RESPONSE_DELETED, WEBHOOK_TAG_CREATED, WEBHOOK_TAG_CHANGED, WEBHOOK_TAG_DELETED
locations array No An array of Locations a particular Hook can be fired from. Valid values are: ContactDirect, Webapp, WebappBulk, System, API
customFieldIds array Yes An array of Custom Field IDs (See: Custom_Field_Get_All) - if specified, the values of the specified fields will be included in the data payload for any Webhook sending contact data
optionalParameters array Yes optionalParameters

Optional Parameters

Name Type Description
bulk bool Set to true to enable bulk webhooks rollup
bulkThreshold int The maximum number of hooks to be included in a single payload, valid values 50 to 10000
bulkJSON bool Send hooks as a single JSON struct rather than a newline delimited collection of JSON structs
bulkReport bool Save reports for 7 days in case a hook is missed (retrieve with Report_Get_Bulk_Webhooks)

Returns

Type Description
bool True on success

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

Name Type Optional Description
key string No Your API key - used to authenticate your account
clientId int No The client ID number you want to modify

Returns

Type Description
bool True on success

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)