Introduction
Sogolytics provides simple and powerful programmatic access to your survey data using a secure application programming interface of Web API. To use this document, you should have a basic familiarity with software development, Web API and the Sogolytics user interface.
The functionality described in this guide is available only in Enterprise accounts enabled for API integration. To enable this option within your Enterprise account, Contact us to take advantage of this option.
Sogolytics is both scalable and extensible, and it embraces open Internet standards for access and consumption.
Sogolytics Web API provides the following verbs for your use:
| Verbs | Description |
|---|---|
| updateContactList() | This method can be used to update and add new records within an existing Contact List. |
| getSurveyURL() | This method can be used to obtain the multi-use link of a survey. |
| sendSurveyInvite() | This method can be used to send email invitations to a list of email addresses. |
| sendSurveyReminder() | This method can be used to send email Reminders to non-participants. |
| generateSurveyKey() | This method can be used to generate Survey Passwords to publish your survey offline. |
| sendSurveyInviteWithReminder() | This method can be used to send email invitations along with reminders to a list of email addresses. |
| getParticipationStatusInfo() | This method can be used to obtain participation status using the participant’s email address. |
| getSurveyList() | This method returns a list of all surveys in the account, including the relevant information. |
| getData() | This method can be used to obtain survey responses in JSON format. |
Customize and Integrate
Customize, integrate, and extend your Sogolytics solution using the language and platform of your choice:
- Create advanced surveys and customize the look and feel by using your own logos, colors, and branding guide in the Sogolytics platform and use the Web API to send them out.
- Integrate Sogolytics with your HR, CRM, or School Portal systems to meet any advanced requirements you or your clients may encounter.
Standards Compliance
The Web API is implemented to comply with the following specifications:
| Status | Reference |
|---|---|
| JavaScript Object Notation (JSON) | https://jsonapi.org/format/ |
| HTTP Verbs (GET, POST, PUT, DELETE) | http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html |
Development Platforms
The Web API can be used in all major programming languages that support HTTP Protocol.
Sample code for Web API usages in C#, VB.NET, Python, PHP and Curl are provided in this document.
Backward Compatibility
Sogolytics strives to make backward compatibility easy for our API users. We maintain support for each API version across releases of the platform software. The API is backward compatible in that an application created to work with a given API version will continue to work with that same API version in future platform software releases. Sogolytics does not guarantee that an application written against one API version will work with future API versions: Changes in method signatures and data representations are often required as we continue to enhance the API. However, we strive to keep the API consistent from version to version with minimal changes required to port applications to newer API versions.
API End-of-Life
Sogolytics is committed to supporting each API version for a minimum of two years from the date of its first release. In order to mature and improve the quality and performance of the API, versions that are more than two years old may cease to be supported. When an API version is to be deprecated, advance end-of-life notice will be given at least six months before support for the API version is ended.
Environment
Access Sogolytics Web API (with JSON Output) by adding the verb name at the end of the URL below:
https://www.sogolytics.com/serviceAPI/service/
HTTP Response Status Codes
We use conventional HTTP response status codes to indicate the success or failure of a Web API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error caused by the information provided (a required parameter was omitted, a method was not found, etc.), and codes in the 5xx range indicate an error with our servers.
| Output Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad request |
| 401 | Unauthorized |
| 500 | Internal Server Error |
Sogolytics Account Enablement
API Integration is only available in our Enterprise plan. Contact us to take advantage of this feature.
Please contact Sogolytics Support with any questions at support1@sogolytics.com.
Once you have enabled API Integration in your account, you'll need to generate an API token for your API verbs.
Here's how:- Click on your account initials in the top right corner, then choose Account Settings from the drop down menu.
- Choose Generate API Token from the left menu.
- Click on Generate Token.
- Copy the Token by clicking on the copy icon.
- You can generate a new token by clicking on Regenerate. Note that, regenerating a token will expire the existing token.