SurveyContact Sub-Object v5

 Help Us Improve Our API Documentation!

We're beginning an initiative to improve our API docs. We would love your help!

Please take this quick 4-question survey to help us out! Thank you in advance for your time!

Note: Contacts records are stored within our system using the email address as the key. A single record per email address is stored per account. Email address and all standard contact fields are are stored at the account level. This means that changes to the standard contact fields of an existing contact will be made globally wherever the contact is present. For more information: http://help.surveygizmo.com/help/article/link/global-vs-campaign-contact-fields.

The following API calls are currently available for the SurveyContact sub-object:

GET LIST - Get a list of all of your contacts for the specified survey and campaign.

https://restapi.surveygizmo.com/v5/survey/123456/surveycampaign/100000/surveycontact

Note: Get requests will cache for 60 seconds. If you make repeated API get requests that are identical, the return will be cached and will thus return identical results.
ParametersExampleRequired
Authentication Credentialsapi_token=5D685159B6964FB69B044D3E7D2676D1True
pagepage=3False
resultsperpageresultsperpage=100False

Response Example (.debug format):

Array
(
    [result_ok] => 1
    [total_count] => 2
    [page] => 1
    [total_pages] => 1
    [results_per_page] => 50
    [data] => Array
        (
            [0] => Array
                (
                    [id] => 100039753
                    [email_address] => jon.doe@surveygizmo.com
                    [first_name] => Jon
                    [last_name] => Doe
                    [organization] => 
                    [division] => 
                    [department] => 
                    [team] => 
                    [group] => 
                    [role] => 
                    [home_phone] => 
                    [fax_phone] => 
                    [business_phone] => 
                    [mailing_address] => 
                    [mailing_address2] => 
                    [mailing_address_city] => 
                    [mailing_address_state] => 
                    [mailing_address_country] => 
                    [mailing_address_postal] => 
                    [title] => Vice President
                    [url] => 
                    [customfield1] => sales
                    [customfield2] => 
                    [customfield3] => 
                    [customfield4] => 
                    [customfield5] => 
                    [customfield6] => 
                    [customfield7] => 
                    [customfield8] => 
                    [customfield9] => 
                    [customfield10] => 
                    [test] => Success
                    [test2] => 
                    [test3] => 
                    [test4] => 
                    [test5] => 
                    [status] => Active
                    [subscriber_status] => Unsent
                    [date_last_sent] => 
                )

            [1] => Array
                (
                    [id] => 100039769
                    [email_address] => jane.doe@surveygizmo.com
                    [first_name] => Jane
                    [last_name] => Doe
                    [organization] => 
                    [division] => 
                    [department] => 
                    [team] => 
                    [group] => 
                    [role] => 
                    [home_phone] => 
                    [fax_phone] => 
                    [business_phone] => 
                    [mailing_address] => 
                    [mailing_address2] => 
                    [mailing_address_city] => 
                    [mailing_address_state] => 
                    [mailing_address_country] => 
                    [mailing_address_postal] => 
                    [title] => 
                    [url] => 
                    [customfield1] => 
                    [customfield2] => 
                    [customfield3] => 
                    [customfield4] => 
                    [customfield5] => 
                    [customfield6] => 
                    [customfield7] => 
                    [customfield8] => 
                    [customfield9] => 
                    [customfield10] => 
                    [test] => 
                    [test2] => 
                    [test3] => 
                    [test4] => 
                    [test5] => 
                    [status] => Active
                    [subscriber_status] => Unsent
                    [date_last_sent] => 
                )

        )

)

subscriber_status is a combination of status log response status and send status. It returns 1 of 5 values:

  • Unsent
  • Sent
  • Bounced
  • Partial - Link clicked and at least one page submitted
  • Complete - Link clicked and response completed

GET CONTACT - Get a information about a specified contact.

https://restapi.surveygizmo.com/v5/survey/123456/surveycampaign/100000/surveycontact/100039753

Note: Get requests will cache for 60 seconds. If you make repeated API get requests that are identical, the return will be cached and will thus return identical results.
ParametersExampleRequired
Authentication Credentialsapi_token=5D685159B6964FB69B044D3E7D2676D1True

Response Example (.debug format):

Array
(
    [result_ok] => 1
    [data] => Array
        (
            [id] => 100039753
            [email_address] => jon.doe@surveygizmo.com
            [first_name] => Jon
            [last_name] => Doe
            [organization] => 
            [division] => 
            [department] => 
            [team] => 
            [group] => 
            [role] => 
            [home_phone] => 
            [fax_phone] => 
            [business_phone] => 
            [mailing_address] => 
            [mailing_address2] => 
            [mailing_address_city] => 
            [mailing_address_state] => 
            [mailing_address_country] => 
            [mailing_address_postal] => 
            [title] => Manager
            [url] => 
            [customfield1] => 
            [customfield2] => 
            [customfield3] => 
            [customfield4] => 
            [customfield5] => 
            [customfield6] => 
            [customfield7] => 
            [customfield8] => 
            [customfield9] => 
            [customfield10] => 
            [test] => wow
            [test2] => 
            [test3] => 
            [test4] => 
            [test5] =>
	    [invitelink] => http://s-123-i.sgizmo.com/s3/abcdefg (unique respondent link)
            [status] => Active
            [subscriber_status] => Unsent
            [date_last_sent] => 
        )

)

*subscriber_status is a combination of status log response status and send status. It returns 1 of 5 values:

  • Unsent
  • Sent
  • Bounced
  • Partial - Link clicked and at least one page submitted
  • Complete - Link clicked and response completed

CREATE CONTACT - Create a new contact.

https://restapi.surveygizmo.com/v5/survey/123456/surveycampaign/100000/surveycontact/?_method=PUT&email_address=newexample@email.com

ParametersExampleRequired
Authentication Credentialsapi_token=5D685159B6964FB69B044D3E7D2676D1True
email_addressexample@email.comTrue
first_nameFirstnameFalse
last_nameLastnameFalse
organizationOrganizationFalse
divisionDivisionFalse
departmentDepartmentFalse
teamTeamFalse
groupGroupFalse
roleRoleFalse
home_phone123-456-7890False
fax_phone123-456-7890False
business_phone123-456-7890False
mailing_address123 Main StFalse
mailing_address2Suite 100False
mailing_address_cityAnycityFalse
mailing_address_stateCOFalse
mailing_address_countryUSFalse
smailing_address_postal12345False
titleTitleFalse
urlwww.website.comFalse
customfield1-10*custom field data 1-10False
custom[fieldname]†custom[customerid]=valueFalse
statusActive, InactiveFalse
allowdupetrueFalse

*These are the custom fields 1-10 that are available as part of the email campaign contact list.
 †These are the custom fields that are available as part of the account email lists. Learn how to get the field name for custom fields.

UPDATE CONTACT - Update a specified contact.

https://restapi.surveygizmo.com/v5/survey/123456/surveycampaign/100000/surveycontact/100030864?_method=POST
ParametersExampleRequired
Authentication Credentialsapi_token=5D685159B6964FB69B044D3E7D2676D1True
email_addressexample@email.comTrue
first_nameFirstnameFalse
last_nameLastnameFalse
organizationOrganizationFalse
divisionDivisionFalse
departmentDepartmentFalse
teamTeamFalse
groupGroupFalse
roleRoleFalse
home_phone123-456-7890False
fax_phone123-456-7890False
business_phone123-456-7890False
mailing_address123 Main StFalse
mailing_address2Suite 100False
mailing_address_cityAnycityFalse
mailing_address_stateCOFalse
mailing_address_countryUSFalse
mailing_address_postal12345False
titleTitleFalse
urlwww.website.comFalse
customfield1-10*custom field data 1-10False
custom[fieldname]†custom[customerid]=valueFalse
statusActive, InactiveFalse

*These are the custom fields 1-10 that are available as part of the email campaign contact list.
 †These are the custom fields that are available as part of the account email lists. Learn how to get the field name for custom fields.
 ‡Updating the contact status to "Inactive" will unsubscribe the contact from the email campaign.

DELETE CONTACT - Delete a specified contact.

https://restapi.surveygizmo.com/v5/survey/123456/surveycampaign/100000/surveycontact/100030864?_method=DELETE

ParametersExampleRequired
Authentication Credentialsapi_token=5D685159B6964FB69B044D3E7D2676D1True

Response Example (.debug format):

Array
(
    [result_ok] => 1
)

Getting Custom Field Name from Email Lists

Go to Account > Email Lists and click the link to Manage Custom Fields in the bottom right. The text that you see in the Custom Field Name column for each field is the text that you will use for either a PUT or a POST.