Upload & Send Invitations

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

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 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

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}}}

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

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."]}]}}