Get Started with the Get Smart API

With the getsmart API, you can upload and send new invitations on your project.

More functionalities will be added in the future to allow you to interact fully with your data.

Before You Start

All getsmart API requests require the following details:

  • Username
    The username or email you use to login to your getsmart account.
  • Project ID
    The unique ID number of your project.
  • Project API Key
    The 32 characters long hexadecimal number of your project.

You will find this information on your getsmart account but remember to select the right project first from the top left dropdown menu.

Authentication

The getsmart API uses the HTTP Basic Authentication. It uses your Username as the username and your Project API Key as the password.

HTTP Methods

The getsmart API supports 2 HTTP methods for interacting with your project:

Get Smart API Reference

All getsmart API requests must have a URL that follows this format:

https://survey.getsmartglobal.com/api/v1/project//

Each Action is associated with a different HTTP method.

Here is an overview of all available resources of the getsmart API with a link to know more about the technical details.

HTTP Method Action Function
GET Test the authentication
POST upload-invitations Upload new invitation records on your project and automatically send them if wanted

Upload & Send Invitations

Upload new invitation records on your project and automatically send them if wanted.

Request

HTTP MethodPOST
Actionupload-invitations
Query String Parameters
sendInteger, OptionalSends the invitations successfully uploaded.
Value is either 1 or true.
Body JSON Parameters
[]Array[Object], RequiredArray of Invitation Objects.
Array count must be greater than 0.

Invitation Object Properties
NameString, RequiredName of the Recipient
EmailString, RequiredEmail of the Recipient.
Value must be a valid email address.
LanguageString, Project Specific *Code of the Language.
Value must be a valid language code.
AnswersObject, Project Specific *Prepopulated Answers.
Property names are the Question ID of the Answer Objects.
Values must be valid Answers.

Answer Object Properties
AnswerString, Project Specific *Main part of the Answer Object.
Requirement and Value depend on the Question it relates to.
Value must be a valid Answer.
CommentString, Project Specific *Comment associated with the Answer.
Requirement depends on the Question and Answer it relates to.
FlagInteger, Project Specific *Property used for "Not Applicable".
Requirement depends on the Question it relates to.
If available, value is 1.

* Some of the properties requirements are specific to your project.


Examples
2 Invitations [No Language, No Answers] 
[{"Name":"John Smith","Email":"john.smith@gmail.com"},{"Name":"Cristine Tee","Email":"cristine.tee@gmail.com"}]
2 Invitations [Language Optional, No Answers] 
[{"Name":"John Smith","Email":"john.smith@gmail.com","Language":"en_NZ"},{"Name":"Cristine Tee","Email":"cristine.tee@gmail.com"}]
2 Invitations [Language Required, No Answers] 
[{"Name":"John Smith","Email":"john.smith@gmail.com","Language":"en_NZ"},{"Name":"Cristine Tee","Email":"cristine.tee@gmail.com","Language":"fr_FR"}]
2 Invitations [Language Required, Question #12345 Optional] 
[{"Name":"John Smith","Email":"john.smith@gmail.com","Language":"en_NZ","Answers":{"12345":{"Answer":"4","Comment":"Good Times!"}}},{"Name":"Cristine Tee","Email":"cristine.tee@gmail.com","Language":"fr_FR"}]
2 Invitations [Language Required, Question #12345 Required] 
[{"Name":"John Smith","Email":"john.smith@gmail.com","Language":"en_NZ","Answers":{"12345":{"Answer":"4","Comment":"Good Times!"}}},{"Name":"Cristine Tee","Email":"cristine.tee@gmail.com","Language":"fr_FR","Answers":{"12345":{"Flag":1}}}]

Response

HTTP Status CodeTypeDescriptionBody JSON Parameters
200SuccessPartial or Complete Upload Successful
UploadObject, RequiredUpload Process Summary
SendObject, OptionalSend Process Summary.
Only present if the send query String parameter was present in the request.
Only contains 1 property Counts.

Upload Object Properties
CountsObject, RequiredUpload Process Summary
RecordErrorsArray[Object], OptionalArray of ErrorsOfRecord Objects.
Only present if Upload.Counts.Fail is greater than 0.
If present, Array count is greater than 0.

Upload.Counts Object Properties
RequestInteger, RequiredNumber of Records requested to be uploaded.
Value is greater than 0.
SuccessInteger, RequiredNumber of Records successfully uploaded.
Value is greater than 0.
FailInteger, RequiredNumber of Records which fail to be uploaded.
Value is greater than or equal to 0.

ErrorsOfRecord Object Properties
IndexInteger, RequiredIndex of Record.
Value is greater than or equal to 0.
ErrorsArray[String], RequiredArray of String Errors.
Array count is greater than 0.

Send.Counts Object Properties
RequestInteger, RequiredNumber of Records requested to be uploaded.
Value is greater than 0.
SuccessInteger, RequiredNumber of Records successfully uploaded.
Value is greater than 0.
FailInteger, RequiredNumber of Records which fail to be uploaded.
Value is greater than or equal to 0.

Examples
Complete Upload of 3 Invitations 
{"Upload":{"Counts":{"Request":3,"Success":3,"Fail":0}}}
Partial Upload of 3 Invitations 
{"Upload":{"Counts":{"Request":3,"Success":2,"Fail":1},"RecordErrors":[{"Index":2,"Errors":["'Name' not found.","'Email' is invalid."]}]}}
Complete Upload of 3 Invitations [Send Requested] & Complete Send 
{"Upload":{"Counts":{"Request":3,"Success":3,"Fail":0}},"Send":{"Counts":{"Request":3,"Success":3,"Fail":0}}}
Complete Upload of 3 Invitations [Send Requested] & Partial Send 
{"Upload":{"Counts":{"Request":3,"Success":3,"Fail":0}},"Send":{"Counts":{"Request":3,"Success":1,"Fail":2}}}
Partial Upload of 3 Invitations [Send Requested] & Complete Send 
{"Upload":{"Counts":{"Request":3,"Success":2,"Fail":1},"RecordErrors":[{"Index":2,"Errors":["'Name' not found.","'Email' is invalid."]}]},"Send":{"Counts":{"Request":2,"Success":2,"Fail":0}}}
Partial Upload of 3 Invitations [Send Requested] & Partial Send 
{"Upload":{"Counts":{"Request":3,"Success":2,"Fail":1},"RecordErrors":[{"Index":2,"Errors":["'Name' not found.","'Email' is invalid."]}]},"Send":{"Counts":{"Request":2,"Success":1,"Fail":1}}}
400ErrorBad Request Syntax
MessageString, RequiredMore information
401ErrorAuthentication Failure
MessageString, RequiredMore information
403ErrorForbidden Action
MessageString, RequiredMore information
405ErrorHTTP Method Issue
MessageString, RequiredMore information
415Error'Content-Type' Header Issue
MessageString, RequiredMore information
422ErrorBody Issue
MessageString, OptionalWrongly Formatted or Empty
UploadObject, OptionalOnly present if Message is not

Upload Object Properties
CountsObject, RequiredUpload Process Summary
RecordErrorsArray[Object], RequiredArray of ErrorsOfRecord Objects.
Array count is greater than 0.

Upload.Counts Object Properties
RequestInteger, RequiredNumber of Records requested to be uploaded.
Value is greater than 0.
SuccessInteger, RequiredNumber of Records successfully uploaded.
Value is 0.
FailInteger, RequiredNumber of Records which fail to be uploaded.
Value is equal to Upload.Counts.Request.

ErrorsOfRecord Object Properties
IndexInteger, RequiredIndex of Record.
Value is greater than or equal to 0.
ErrorsArray[String], RequiredArray of String Errors.
Array count is greater than 0.

Examples
Body from Request was an empty JSON [] 
{"Message":"JSON is empty."}
None of 3 Invitations Uploaded 
{"Upload":{"Counts":{"Request":3,"Success":0,"Fail":3},"RecordErrors":[{"Index":0,"Errors":["'Language' is an empty string."]},{"Index":1,"Errors":["'222' is not a set."]},{"Index":2,"Errors":["'Name' not found.","'Email' is invalid."]}]}}

Test Authentication

Test if the authentication is successful by calling the API Root of your project and leaving the Action empty as explained below.

Request

HTTP Method GET
Action

Response

HTTP Status Code Type Description Body JSON Parameters
200 Success Authentication Successful
Message String, Required More information
400 Error Bad Request Syntax
Message String, Required More information
401 Error Authentication Failure
Message String, Required More information
405 Error HTTP Method Issue
Message String, Required More information

Upload new invitation records on your project and automatically send them if wanted.

Request

HTTP Method POST
Action upload-invitations
Query String Parameters
send Integer, Optional Sends the invitations successfully uploaded. Value is either 1 or true.
Body JSON Parameters
[] Array[Object], Required Array of Invitation Objects. Array count must be greater than 0.

 

Invitation Object Properties
Name String, Required Name of the Recipient
Email String, Required Email of the Recipient. Value must be a valid email address.
Language String, Project Specific * Code of the Language. Value must be a valid language code.
Answers Object, Project Specific * Prepopulated Answers. Property names are the Question ID of the Answer Objects. Values must be valid Answers.

 

Answer Object Properties
Answer String, Project Specific * Main part of the Answer Object. Requirement and Value depend on the Question it relates to. Value must be a valid Answer.
Comment String, Project Specific * Comment associated with the Answer. Requirement depends on the Question and Answer it relates to.
Flag Integer, Project Specific * Property used for "Not Applicable". Requirement depends on the Question it relates to. If available, value is 1.

 

* Some of the properties requirements are specific to your project.

 

Examples

Response

HTTP Status Code Type Description Body JSON Parameters
200 Success Partial or Complete Upload Successful
Upload Object, Required Upload Process Summary
Send Object, Optional Send Process Summary. Only present if the send query String parameter was present in the request. Only contains 1 property Counts.

 

Upload Object Properties
Counts Object, Required Upload Process Summary
RecordErrors Array[Object], Optional Array of ErrorsOfRecord Objects. Only present if Upload.Counts.Fail is greater than 0. If present, Array count is greater than 0.

 

Upload.Counts Object Properties
Request Integer, Required Number of Records requested to be uploaded. Value is greater than 0.
Success Integer, Required Number of Records successfully uploaded. Value is greater than 0.
Fail Integer, Required Number of Records which fail to be uploaded. Value is greater than or equal to 0.

 

ErrorsOfRecord Object Properties
Index Integer, Required Index of Record. Value is greater than or equal to 0.
Errors Array[String], Required Array of String Errors. Array count is greater than 0.

 

Send.Counts Object Properties
Request Integer, Required Number of Records requested to be uploaded. Value is greater than 0.
Success Integer, Required Number of Records successfully uploaded. Value is greater than 0.
Fail Integer, Required Number of Records which fail to be uploaded. Value is greater than or equal to 0.

 

Examples
400 Error Bad Request Syntax
Message String, Required More information
401 Error Authentication Failure
Message String, Required More information
403 Error Forbidden Action
Message String, Required More information
405 Error HTTP Method Issue
Message String, Required More information
415 Error 'Content-Type' Header Issue
Message String, Required More information
422 Error Body Issue
Message String, Optional Wrongly Formatted or Empty
Upload Object, Optional Only present if Message is not

 

Upload Object Properties
Counts Object, Required Upload Process Summary
RecordErrors Array[Object], Required Array of ErrorsOfRecord Objects. Array count is greater than 0.

 

Upload.Counts Object Properties
Request Integer, Required Number of Records requested to be uploaded. Value is greater than 0.
Success Integer, Required Number of Records successfully uploaded. Value is 0.
Fail Integer, Required Number of Records which fail to be uploaded. Value is equal to Upload.Counts.Request.

 

ErrorsOfRecord Object Properties
Index Integer, Required Index of Record. Value is greater than or equal to 0.
Errors Array[String], Required Array of String Errors. Array count is greater than 0.

 

Examples