Survey Contacts from an Existing Database

 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!

Pulling contacts from an existing database for the purposes of surveying or other otherwise gathering information is one of the most common uses of the SurveyGizmo API. In this use-case example we'll cover how to create a campaign, add contacts, and send the campaign emails.

Step 1: Create a New Campaign

To begin, we'll create a new campaign with a create (PUT) SurveyCampaign call. (We're assuming there is an existing survey.)

https://restapi.surveygizmo.com/v4/survey/123456/surveycampaign?_method=PUT&type=email&name=New%20Campaign

The return will look like the below return. You'll need to parse the return for the id that will be used in the next call.

Notice there is also an inviteid present already. When you create a campaign, using the API or the UI, a default message is created. So, while you might think your next step is to use the EmailMessage object to create a message, you don't need to!

Array
(
    [result_ok] => 1
    [data] => Array
        (
            [id] => 1234567
            [inviteid] => 123456
            [_type] => SurveyCampaign
            [_subtype] => email
            [__subtype] => standard
            [status] => Active
            [name] => New Campaign
            [uri] => s-12de70-i.sgizmo.com/s3/
            [SSL] => False
            [tokenvariables] => 
            [limit_responses] => 
            [close_message] => 
            [language] => 
            [datecreated] => 2015-12-01 21:15:51
            [datemodified] => 2015-12-01 21:15:51
        )

)

Step 3: Add Contacts

With your id handy from the create SurveyCampaign call, you'll make a series of create (PUT) contact calls, one for each contact, to add contacts to the newly created campaign using the Contact sub-object.

https://restapi.surveygizmo.com/v4/survey/123456/surveycampaign/1234567/contact?_method=PUT&semailaddress=example@email.com

Step 3: Get Message ID

Once you are finished adding contacts you are ready to customize your email message. When you create a new campaign, a default message is added so you'll need to get the id for this message with an EmailMessage GET call like so:

https://restapi.surveygizmo.com/v4/survey/123456/surveycampaign/1234567/emailmessage?_method=GET

Review the return, make note of your the id as well as the default values/text for the following fields that can be modified via an EmailMessage update (POST):

  • from[name]
  • from[email]
  • replies
  • subject
  • messagetype
  • body[text]
  • body[html]
Array
(
    [result_ok] => 1
    [total_count] => 1
    [page] => 1
    [total_pages] => 1
    [results_per_page] => 1
    [data] => Array
        (
            [0] => Array
                (
                    [id] => 1150520
                    [_type] => EmailMessage
                    [_subtype] => message
                    [messagetype] => plaintext
                    [medium] => Email
                    [invite_identity] => 630845
                    [status] => Building
                    [from] => Array
                        (
                            [email] => surveys@sgizmo.com
                            [name] => Survey Research
                        )

                    [subject] => Help out by taking this survey.
                    [body] => Array
                        (
                            [text] => Hi
I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes.

[invite("survey link")]

Thank You!
                            [html] => Hi
I'm currently running a study. If you don't mind, please fill out this survey -- it should only take a few minutes.

Begin

Thank You!
                        )

                    [sfootercopy] => This message was sent by [account("physical address")].
To unsubscribe, click below:
[invite("unsubscribe link")]
                    [datecreated] => 2015-12-04 14:38:35
                    [datemodified] => 2015-12-04 14:38:35
                )

        )

)

Step 4: Update Message with Desired Customizations and Set send=true

Your next step will be to update (POST) the message with the EmailMessage object with any of the desired customizations you wish to make to the default message and the send=true parameter (if you are ready to send).

https://restapi.surveygizmo.com/v4/survey/123456/surveycampaign/1234567/emailmessage/1150520?_method=POST&messagetype=html&from[name]=bri&from[email]-bri@sgizmo.com&subject=We%20need%20your%20feedback!&send=true

The return will confirm that the message is sending.

Array
(
    [result_ok] => 1
    [0] => Sending...
)