Submit Project API

This API is used to submit a project. A project will be created and two default datapoints will be added (Age 18-99 and Gender M/F). Call the addDatapoints API subsequently to override these defaults.

Command

"client/submitProject/1"



Inputs

The following values are expected in the JSON body:

Name Type Required Description
command String

Must be "client/submitProject/1"
pid String

A unique identifier for your project.
name String

Internal name describing the survey.
title String

Text to be shown to the respondent describing the survey.
country String

2-letter ISO country code, e.g. US, GB, CA, etc.
ir Integer

Incidence Rate of the project as a percent.
lengthOfInterview Integer

Average number of minutes it takes a user to complete your survey.
surveyURL String

Survey URL where we will send our panelists to take the survey. The link should contain a placeholder {sesskey} which we will replace with a unique session identifier to track respondents. For example:
http://the.link.to.the.survey/survey?sesskey={sesskey}
desiredCompletes Integer

Indicates the amount of completes that you want to accomplish on this project.
collectsPII Boolean

Indicates if the project asks for personal identifiable information.
notificationEmail String

The email address to receive notifications, if a project was paused due to conversion rules.
endOfFieldDate Date

Date survey is meant to end (yyyy-MM-dd or yyyy-MM-dd'T'HH:mm:ss'Z' format). Only used to evaluate project performance. Client must pause and close project when appropriate.
customerId String

Your internal ID for your customer.
customerManager String

The name of the manager of your internal customer.
contact Object

Primary contact for this project. The JSON should have the following keys:

{
     first: 'Tom',
     last: 'Jones',
     phone: '(123)456-7890',
     email: 'tom@somewhere.com'
}
duplicationKey String

Duplication key used by this project.

Different projects can be grouped using a duplicationKey. The duplicate check will be applied considering the whole group instead of a single project. (This field will only be present if the project is part of a group)
filterMode Integer

Indicates how the respondent will be considered as a duplicate in a group: based on starts or based on completes.

  1. Starts
  2. Completes

(This field is mandatory if the project is part of a group)
quotaLimitBy String

Indicates if the quota limits are set by completes or starts. The possible values are:

  • completes
  • starts

Defaults to completes. (This field will only be present if the project has quotas)
excludeNonMatching Boolean

Indicates if respondents not matching any quotas will be rejected.
Defaults to false.
(This field is only necessary if the project has quotas)
surveyCategory Integer

See integer codes in appendix
phoneSupported Integer

Survey can be displayed on a phone. Defaults to Unknown.

  1. Unknown
  2. Yes
  3. No
tabletSupported Integer

Survey can be displayed on a tablet. Defaults to Unknown.

  1. Unknown
  2. Yes
  3. No

Outputs

The JSON output will always contain the original command and a result. If the result > 0, an error has occurred (refer to Error Codes) and a message field will describe the error. If result = 0, the following is included in the response field:

Name Type Description
rfg_id String

RFG identifier for your project. Can be null if there were problems while validating and creating your project.
callbacks Object 
{
     "complete":Callback to use for completes,  
     "terminate": Callback to use for terminates,  
     "quota": Callback to use for quotas,  
     "security": Callback to use for security concerns  
}

Example Command

{  
     command: "client/submitProject/1",  
     pid: "1234",  
     name: "Internal Survey 123456",  
     title: "We need your opinion on this!",  
     country: "US",  
     ir: 60,  
     lengthOfInterview: 15,  
     surveyURL: "http://survey.server.com/survey/x123456?sesskey={sesskey}",  
     desiredCompletes: 200,  
     collectsPII: false,  
     quotaLimitBy: "completes",  
     excludeNonMatching: false,  
     notificationEmail: "notify@somewhere.com",  
     endOfFieldDate: "2016-12- 20",  
     customerId: "Acme 123",  
     customerManager: "Joe Blow",  
     duplicationKey: "8999",  
     filterMode: 1,  
     mobileOptimized: true,  
     surveyCategory: 22
}

Example Response

"response" : {  
     rfg_id: "RFG12345-001",  
     callbacks:{  
          complete:"http://survey.saysoforgood.com/result?result=C&sesskey={sesskey}",  
          terminate:"http://survey.saysoforgood.com/result?result=T&sesskey={sesskey}",  
          quota:"http://survey.saysoforgood.com/result?result=Q&sesskey={sesskey}",  
          security:"http://survey.saysoforgood.com/result?result=S&sesskey={sesskey}"  
     }
}