Using the API to send a Survey Invitation

It's possible to use the API to trigger the sending of an email or SMS invitation to a survey.

Setting up the Invitation

The API can only trigger the send of invitations that have already been sent at least once. this means there are three setup steps that need to be taken before this feature can be used.

1. Create an Email or SMS contact list. It must contain at least one test contact.
2. Create an invitation in the survey you wish to send the invite for. Edit the Email or SMS message as required.
3. Send the invitation to your test contact. Once this is done, and the invitation status is "Sent", the invitation can be triggered via the API.

Triggering the Invitation (one at a time)

The Endpoint:

The invitation can be triggered by sending a request to the following endpoint URL:

https://api.smartsurvey.io/v2/surveys/{surveyId}/invitations/{invitationId}/sendone

For more information, check the API reference for this endpoint.

You will need to authenticate the request via the header using Basic Auth.

Required URL Variables:

• surveyId: The survey ID. You can see this in the URL when editing a survey.
  E.g. https://app.smartsurvey.co.uk/c/surveys/000001/design
   
• invitationId: The invitation ID can be found in the URL when viewing an invitation on SmartSurvey.
  E.g: https://app.smartsurvey.co.uk/c/surveys/12345/collect/view-message/000001

This endpoint needs to be sent data about the recipient in JSON format. It handles both Email and SMS invitations.

Sample Request Body for Email Invite:

To send to an email invitation, you will need to include the "email" property. For example:

{
    "name": "John Smith",
    "email": "john@smartsurvey.com",
    "custom_columns": [
                {"name" : "age", "value":"30"},
                {"name" : "column_name", "value":"value"}
    ]
}

Sample Request Body for SMS Invite:

To send to an email invitation, you will need to include the "mobile" property. For example:

{
    "name": "John Smith",
    "mobile": "07595123123",
    "custom_columns": [
                {"name" : "age", "value":"30"},
                {"name" : "column_name", "value":"value"}
    ]
}

The custom_columns property is optional.

Triggering the invitation (Multiple Contacts)

The Endpoint:

The invitation can be triggered by hitting the following Endpoint URL:

https://api.smartsurvey.io/v2/surveys/{surveyId}/invitations/{invitationId}/send

For more information, check the API reference for this endpoint

You will need to authenticate the request via the header using Basic Auth.

Required URL Variables:

• surveyId: The survey ID. You can see this in the URL when editing a survey.
  E.g. https://app.smartsurvey.co.uk/c/surveys/000001/design
   
• invitationId: The invitation ID can be found in the URL when viewing an invitation on SmartSurvey.
  E.g: https://app.smartsurvey.co.uk/c/surveys/12345/collect/view-message/000001

This endpoint needs to be sent data about the recipients in JSON format. It handles both Email and SMS invitations.

Each contact needs to be added as a seperate object. the format of each object is the same as for a single send.