Survey Solutions Application

Survey Solutions API client for Stata
S.Radyakin
sradyakin@worldbank.org
April 8, 2021
Contents
1 Survey Solutions API Client for Stata 3
1.1 Create a new API client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Questionnaires 5
2.1 Get a list of questionnaires on the server . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Get a list of interviews of a questionnaire on the server . . . . . . . . . . . . . . . . 5
2.3 Get a questionnaire document in JSON format . . . . . . . . . . . . . . . . . . . . . 6
2.4 Set audio audit for the survey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Get status of audio audit for the survey . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Assignments 8
3.1 Get details of an assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2 Assign an assignment to a new responsible . . . . . . . . . . . . . . . . . . . . . . . 8
3.3 Archive an assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.4 Unarchive an assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.5 Close an assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.6 Change quantity for an assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.7 Get quantity setting for an assignment . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.8 Get audio audit status for an assignment . . . . . . . . . . . . . . . . . . . . . . . . 10
3.9 Set audio audit status for an assignment . . . . . . . . . . . . . . . . . . . . . . . . 11
3.10 Get assignment’s history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.11 Create an assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4 Interviews 14
4.1 Approve an interview by a supervisor . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2 Reject an interview by a supervisor . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.3 Unapprove an interview by a headquarters user . . . . . . . . . . . . . . . . . . . . 15
4.4 Approve an interview by a headquarters user . . . . . . . . . . . . . . . . . . . . . . 15
4.5 Reject an interview by a headquarters user . . . . . . . . . . . . . . . . . . . . . . . 15
4.6 Get a PDF document for the interview . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.7 Get statistics for the interview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.8 Get history of the interview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.9 Get answers of the interview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.10 Delete an interview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.11 Assign an interview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.12 Assign supervisor/team to an interview . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.13 Add a comment to a question in the interview by question GUID . . . . . . . . . . 18
4.14 Add a comment to a question in the interview by variable name . . . . . . . . . . . 18
5 Data export 20
5.1 Download data export file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
6 Maps 22
6.1 Get list of maps and maps-to-user assignments . . . . . . . . . . . . . . . . . . . . . 22
6.2 Add an assignment of a map to a user. . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.3 Delete an assignment of a map from a user. . . . . . . . . . . . . . . . . . . . . . . 23
1
6.4 Delete a map from the server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7 Server notice message 24

7.1 Set or change a server notice message . . . . . . . . . . . . . . . . . . . . . . . . . . 24
7.2 Retrieve the currently set server notice message . . . . . . . . . . . . . . . . . . . . 24
7.3 Delete/clear the currently set server notice message . . . . . . . . . . . . . . . . . . 24
8 Users and user accounts 25

8.1 Return information about the current user account . . . . . . . . . . . . . . . . . . 25
8.2 Create a user account on the server . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.3 Get the details of a user account on the server . . . . . . . . . . . . . . . . . . . . . 26
8.4 Get the details of a supervisor account on the server . . . . . . . . . . . . . . . . . . 26
8.5 Get the details of an interviewer account on the server . . . . . . . . . . . . . . . . 27
8.6 Get the list of the supervisor accounts on the server . . . . . . . . . . . . . . . . . . 27
8.7 Get the list of interviewer accounts in a team . . . . . . . . . . . . . . . . . . . . . 28
8.8 Archive a user account on the server . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.9 Unarchive a user account on the server . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.10 Obtain a detailed actions log for an interviewer account . . . . . . . . . . . . . . . . 28
9 Calendar events 30
9.1 Add or update a calendar event to an interview . . . . . . . . . . . . . . . . . . . . 30
9.2 Delete a calendar event to an interview . . . . . . . . . . . . . . . . . . . . . . . . . 30
10 Workspaces 32
10.1 Obtain list of workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
10.2 Get details of a workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
10.3 *Create a workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
10.4 *Delete a workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
10.5 *Obtain workspace status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
10.6 *Disable a workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
10.7 *Enable a workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
10.8 *Assign users to workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
10.9 Update a workspace title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
11 Photo credits 37
12 HTTP Status codes 38
13 Glossary 39
2
1 Survey Solutions API Client for Stata
Survey Solutions API client for Stata is a software that facilitates the control of a Survey
Solutions data server from Stata scripts.
Requirements:
• Stata 16.0 or newer.
• Python 3.8 or newer (installed and accessible from Stata).
Compatibility with The World Bank Survey Solutions:

• This software has been written with Survey Solutions v21.01.8 in mind, which is the current
version at the time of this writing.
• Earlier versions may not implement all the functionality that is required for it, please update
the Survey Solutions server.
• Future versions of Survey Solutions may change the behavior of the quieries or the formats
of responses. If you encounter any incompatibility, please check the release notes of Survey
Solutions and see if an update is available for this API client.
Where to get:
3
• Stata: https://www.stata.com
• Python: https://www.python.org/downloads/
• This API client: in Stata command prompt type ssc install susoapi
• Survey Solutions server: https://mysurvey.solutions/download
Checking Python from Stata.
When you type the following command in Stata:
python : import s y s ; p r i n t ( s y s . v e r s i o n )
you should receive a response indicating Python version. For example:
3.8.1 (tags/v3.8.1:1b293b6, Dec 18 2019, 23:11:46) [MSC v.1916 64 bit (AMD64)].
If you are getting an error, then your Python installation is unusable from Stata. Refer to the
Stata manual/support on how to install and configure Python for integration with Stata.
1.1 Create a new API client

. new s e r v e r username password
Parameters
• server - URL of the server, for example: "https://demo.mysurvey.solutions"
• username - name of the API user account, for example, "WeeklyAPI "
• password - API account password, for example, "VERY321secret"
4
2 Questionnaires
2.1 Get a list of questionnaires on the server

. qx_list , frame ( string )
Options
• frame - (optional) frame name where to save the list. If not specified, the current frame is
cleared and used to store the list.
Questionnaires list frame data structure

str40 qx_identity
str32 qx_id
long qx_version
strL qx_title
str32 qx_var
strL qx_lastentry
2.2 Get a list of interviews of a questionnaire on the server

. qx_interviews , qguid ( string ) qversion ( integer ) [ frame ( string )]
5
Options
• qguid - questionnaire guid identifier.
• qversion - questionnaire version.
• frame - (optional) name of the frame to save the list of the interviews.
Interviews list frame data structure

str36 interview__id
str36 qx_guid
long qx_version
long assignment_id
str36 responsible_guid
str36 responsible_name
long errors_count
str36 status
strL lastentry
byte received_by_device
strL received_by_device_at_utc
2.3 Get a questionnaire document in JSON format

. qx_document , qguid ( string ) qversion ( integer ) saveto ( string ) [ replace ]
Options
• qguid - GUID of the questionnaire as a string, for example:

"2d9d305f-fcc8-468c-9c7a-b3468d8204a7"
• qversion - version of the questionnaire as imported to the HQ, numeric, for example: 2
• saveto - name of the file to be saved, for example: "C:/Temp/qx.json"
• replace - (optional) allow overwriting the output file
2.4 Set audio audit for the survey

. qx_setaudio qguid qversion value
Parameters

"2d9d305f-fcc8-468c-9c7a-b3468d8204a7"
• value - new mode of audio audit: 1=ON or 0=OFF.
6
2.5 Get status of audio audit for the survey
. qx_getaudio qguid qversion
Parameters

"2d9d305f-fcc8-468c-9c7a-b3468d8204a7"
Saved results
• r(record_audio) - numeric 1=ON or 0=OFF.
• r(status_code) - numeric status code for API query. Successful completion is indicated by
code 200.
7
3 Assignments
3.1 Get details of an assignment

. assignments_getdetails assignmentid
Parameters
• assignmentid - numeric identifier of the assignment, for example: 1007.
Errors
• Error 5001 is returned if the assignmentid is not specified.
3.2 Assign an assignment to a new responsible

. assignments_assign assignmentid responsiblelogin
Parameters
• responsiblelogin - account name of the new responsible, for example: "Maryna".
8
Errors
• Error 5002 is returned if the responsiblelogin is not specified.
3.3 Archive an assignment

. assignments_archive assignmentid
Parameters
Errors
3.4 Unarchive an assignment

. assignments_unarchive assignmentid
Parameters
Errors
3.5 Close an assignment

. assignments_close assignmentid
Parameters
Errors
9
3.6 Change quantity for an assignment
. assignments _c ha ng e qu an ti t y assignmentid number
Parameters
• number - new quantity for the assignment, for example: 10.
Errors
• Error 5002 is returned if the number is not specified.
3.7 Get quantity setting for an assignment

. assi gnment s _ g e t q u a n t i t y s e t t i n g s assignmentid
Parameters
• number - new quantity for the assignment, for example: 10.
Saved results
• r(can_change_quantity) - numeric 1=quantity can be changed or 0=quantity cannot be
changed.
code 200.
Errors
3.8 Get audio audit status for an assignment

. assignments_getaudio assignmentid
Parameters
Saved results
10
code 200.
Errors
3.9 Set audio audit status for an assignment

. assignments_setaudio assignmentid value
Parameters
• value - numeric value for the audio audit status of the assignment (0=OFF, any other
value=ON), for example: 1.
Saved results
code 200.
Errors
• Error 5002 is returned if the value of audio audit is not specified.
3.10 Get assignment’s history

. assignments_history assignmentid frame
Parameters
• framename - (optional) frame name where to save the assignment history, for example: "his-
tory". If not specified, the history is saved to the current frame.
Assignment history frame data structure

str32 utc_date (for example, "2020-10-05T15:33:30.317233Z ")
str32 action (for example, "Created ")
str32 actor_name (for example, "ValeriaHQ")
strL additional_data (for example, "{’Comment’: None, ’Responsible’: ’SergiyInt’}")
Errors
11
• Error -10404 is returned if the assignment with assignmentid is not found on the server.
3.11 Create an assignment

. assignments_create , responsible () qxguid () [ qxversion () quantity ()]
[ email () password () webmode ()]
[ audio () comment () protected () data ()]
Options
• responsible - account name of a person designated responsible for the assignment, for ex-
ample: SergiyInt. NB: for web interviews the responsible must be a user in the interviewer
role.
• qxguid() - GUID of the questionnaire.
• qxversion() - (optional) numeric version of the questionnaire (as assigned when the ques-
tionnaire is imported to the HQ), for example: 2. When the option is not specified version 1
is implied.
• quantity() - (optional) quantity of interviews requested in this assignment, for example: 12.
When the option is not specified, quantity 1 is implied.
• email() - (optional) respondent’s email for sending the invitations and reminders for a web
interview.
• password() - (optional) password for accessing the web interview online.
• webmode() - (optional) whether the assignment should be created in web mode. Specify 1 for
web mode assignments, and 0 for regular assignments. If the option is not specified, regular
assignments will be created.
• audio() - (optional) whether audio audit should be collected for this assignment (1=on,
0=off). If the option is not specified, the audio audit will not be collected.
• comment() - (optional) a comment to be recorded as an additional instruction regarding this

assignment to the person who is designated responsible.
• protected() - (optional) a space-delimited list of variables to be protected from modification

by the interviewer (see the corresponding article in the documentation for Survey Solutions).
For example, "memberscount plotslist". If the option is not specified, no variables are pro-
tected.
• data() - (optional) output of the .buildvars method or manually constructed preloading

data in the same format, for example: ""Variable":"age", "Answer":41"
Errors
12
• Error 7001 is returned if the password option is specified, but the assignment is created not
in web mode (option webmode is 0).
• Error 7002 is returned if the email option is specified, but the assignment is created not in
web mode (option webmode is 0).
• Error 7003 is returned if the quantity option is more than 1, but the assignment is created
not in web mode (option webmode is 0).
13
4 Interviews
4.1 Approve an interview by a supervisor

. interviews_approve guid [ comment ]
Parameters
• guid - GUID identifier of the interview to be approved.
• comment - (optional) comment, if specified will be recorded as a comment to the transaction.
4.2 Reject an interview by a supervisor

. interviews_reject guid [ comment ] [ responsibleguid ]
Parameters
• guid - GUID identifier of the interview to be rejected.
• responsibleguid - (optional) GUID identifier of the new person responsible for the rejected
interview.
14
4.3 Unapprove an interview by a headquarters user
. interviews_unapprove guid [ comment ]
Parameters
• guid - GUID identifier of the interview to be unapproved.
4.4 Approve an interview by a headquarters user

. interviews_hqapprove guid [ comment ]
Parameters
• guid - GUID identifier of the interview to be approved.
4.5 Reject an interview by a headquarters user

. interviews_hqreject guid [ comment ] [ responsibleguid ]
Parameters
• guid - GUID identifier of the interview to be rejected.
• responsibleguid - (optional) GUID identifier of the new person responsible for the rejected
interview.
4.6 Get a PDF document for the interview

. interviews_getpdf guid saveto
Parameters
• guid - GUID identifier of the interview.
• saveto - name of the file where the PDF document for this interview must be saved.
15
4.7 Get statistics for the interview
. interviews_getstats guid
Parameters
Saved results
• r(InterviewId) - GUID of the interview, for example: "81784070-1e55-457c-b32e-b52d9672d9c4";
• r(InterviewKey) - interview key, for example: "12-34-56-78";
• r(Status) - status of the interview, for example: "Completed";
• r(ResponsibleId) - GUID of the responsible person, for example: "39ad7fa7-4215-468b-9861-
9a68b20662c2"
• r(ResponsibleName) - login name of the current responsible, for example: "SergiyHQ";
• r(InterviewDuration) - duration of the interview, for example: "00:14:48.3716360"
• r(UpdatedAtUtc) - date and time of the last update to the interview data, for example:
"2021-03-19T13:00:40.048662Z";
• r(AssignmentId) - numeric assignment ID from which this interview has been started, for
example: 30711 ;
• r(NumberRejectionsByHq) - number of rejections by HQ user(s), for example: 0.
• r(NumberRejectionsBySupervisor) - number of rejections by supervisor user(s), for example:
2.
• r(NumberOfInterviewers) - number of interviewers that this interview was processed by, for
example: 1.
• r(ForSupervisor) - number of supervisor questions, for example: 3.
• r(ForInterviewer) - number of questions for interviewer, for example: 100.
• r(WithComments) - number of questions with comments, for example: 4.
• r(Invalid) - number of questions with errors, for example: 1.
• r(Valid) - number of questions without errors, for example: 99.
• r(Flagged) - number of questions with flags, for example: 0.
• r(NotFlagged) - number of questions without flags, for example: 100.
• r(Answered) - number of questions which have been answered, for example: 93.
• r(NotAnswered) - number of questions which have not been answered, for example: 7.
4.8 Get history of the interview

. interviews_gethistory guid framename
Parameters
• framename - (optional) name of the frame where the history of the interview must be saved.
If not specified, the current frame is used.
Interview history frame data structure
16
string* timestamp (for example, "2021-03-19T13:00:13.263127Z ")
string* offset (for example, "-04:00:00 ")
string* action (for example, "Created ")
string* originator_name (for example, "MariaHQ")
string* originator_role (for example, "Interviewer ")
string* parameters (for example, "{’question’: ’OPZ401Q’, ’answer’: ’750000’, ’roster’:
’1,3’}")
*NB: The exact storage types of the string variables depend on the content length and may vary.
4.9 Get answers of the interview

. interviews_getanswers guid framename
Parameters
• framename - (optional) name of the frame where the answers of the interview must be saved.
If not specified, the current frame is used.
Interview answers frame data structure

string* variablename (for example, "hhsize")
str36 questionid (for example, "50756294-eca7-4765-b94d-2f607dc049a0 ")
string* rostervector (for example, "[1, 3] ")
strL answer (for example, "6 ")
*NB: The exact storage types of the string variables depend on the content length and may
vary.
4.10 Delete an interview

. interviews_delete guid
Parameters
Errors
• Error 197 is returned if the guid is not specified.
• Error 10101 is returned if the interview with ID guid is not found.
• Error 10102 is returned if the interview with ID guid may not be deleted.
17
4.11 Assign an interview
. interviews_assign intguid responsibleguid
Parameters
• intguid - GUID identifier of the interview.
• responsibleguid - GUID identifier of the new responsible.
4.12 Assign supervisor/team to an interview

. interviews_ s u pe r vi s o ra s si g n intguid responsibleguid
Parameters
• intguid - GUID identifier of the interview.
• responsibleguid - GUID identifier of the new responsible.
4.13 Add a comment to a question in the interview by question GUID

. interviews_comment , interviewguid () questionguid ()
comment () [ rostervector ()]
Options
• interviewguid() - GUID identifier of the interview.
• questionguid() - GUID identifier of the question where the comment must be added. NB: if
GUID of the question is not known, see next section 4.14 for the equivalent method utilizing
the variable name instead.
• comment() - text of the comment that must be added, for example: comment("Strange value")
• rostervector() - rostervector address of the item if the question is part of the roster, for ex-
ample: rostervector(5). NB: rostervector() (if specified) is expected to be formatted according
to the Survey Solutions rules: specifically as #, or #-#, or #-#-#, or #-#-#-#.
4.14 Add a comment to a question in the interview by variable name

. interviews_varcomment , interviewguid () varname ()
comment () [ rostervector ()]
Options
• interviewguid() - GUID identifier of the interview.
18
• varname() - variable name of the question where the comment must be added. NB: if varname
of the question is not known, see previous section 4.13 for the equivalent method utilizing the
question GUID instead.
• comment() - text of the comment that must be added, for example: comment("Strange value")
• rostervector() - rostervector address of the item if the question is part of the roster, for ex-
ample: rostervector(5). NB: rostervector() (if specified) is expected to be formatted according
to the Survey Solutions rules: specifically as #, or #-#, or #-#-#, or #-#-#-#.
19
5 Data export
5.1 Download data export file

. export2 , qid () saveto () [ replace ]
[ translationid () includemeta
status () exporttype () from () to () ]
Exports data from Survey Solutions server based on the v2 data export (available in Survey
Solutions version 20.07 or newer).
Options
• qid - questionnaire id, for example: "50756294-eca7-4765-b94d-2f607dc049a0$13". A ques-

tionnaire id consists of the questionnaire GUID and a version number on the server concate-
nated with a dollar sign.
• saveto - name of the file to save the exported date, for example: "C:/data/export.zip".
• replace - (optional) if specified, allows to overwrite the file if it already exists.
• translationid - GUID of the translation of the questionnaire, for example: "2075f291-eca2-

4965-b24d-7f607dc049e2".
• includemeta - (optional) if specified this option requests meta-information to be included

in the export file (specify "true" to include, and "false" to exclude the metadata). If not
20
specified, the meta-information about the questionnaire (JSON-document, PDF-documents,
etc) is excluded.
• status - (optional) filter by interview status. If specified, exported interviews data will be
restricted to the data from interviews in that status, otherwise by default the data from all
interviews is exported.
• exporttype - (optional) type of data file requested for export, can be one of the data types
listed below. For example: "Paradata". If not specified, then "STATA"is assumed.
• from - (optional), if specified, restricts the export to interviews modified since the specified
date, for example: "2021-01-01T19:23:43.375Z ". NB: if option from() is specified, then option
to() must also be specified.
• to - (optional), if specified, restricts the export to interviews modified before the specified
date, for example: "2021-01-01T19:23:43.375Z ". NB: if option to() is specified, then option
from() must also be specified.
Data types for export files:

• "Tabular" - tab-delimited survey data (*.tab);
• "STATA" - survey data in Stata format (*.dta);
• "SPSS" - survey data in SPSS format (*.sav);
• "Binary" - binary survey data (images, audio recordings);
• "DDI" - DDI descriptor of the data;
• "Paradata" - survey paradata.
Statuses for the status filter:

• "All"
• "InterviewerAssigned"
• "Completed"
• "ApprovedBySupervisor"
• "ApprovedByHeadquarters"
21
6 Maps
6.1 Get list of maps and maps-to-user assignments

. maps_getmaps maps [ users ]
Parameters
• maps - frame name for placing the list of maps currently on the server
• users - (optional) frame name for placing the list of users-to-maps assignments.
Maps frame data structure

string* filename
string* importdate
long size
long users
long wkid
double minscale
double maxscale
double xminval
double xmaxval
double yminval
22
double ymaxval
User-maps frame data structure

string* filename
string* username
6.2 Add an assignment of a map to a user.

. maps_addusertomap map user
Parameters
• map - name of the map from the list of maps currently on the server, for example, "ukraine.tif "
• user - interviewer account name, for example "SergiyInt".
6.3 Delete an assignment of a map from a user.

. maps_deleteuserfrommap map user
Parameters
• user - interviewer account name, for example "SergiyInt".
6.4 Delete a map from the server.

. maps_deletemap map
Parameters
23
7 Server notice message
7.1 Set or change a server notice message

. notice_set message
Parameters
• message - New message to be set up on the server as a notice message.
7.2 Retrieve the currently set server notice message

. notice_get
This method has no parameters or options.
The message is returned as a result of the call to this method. For example, to display the
currently set notice message execute the following:
display `" `. apiclient . notice_get '" '
7.3 Delete/clear the currently set server notice message

. notice_delete
24
8 Users and user accounts
8.1 Return information about the current user account

. users_reflect
Saved results
As a result of execution of this method, the following properties of the API-client are updated:
• .userid - GUID of the user account.
• .userroles - roles that the account is having in the server, typically "APIUSER" for API user
accounts.
• .userworkspaces - list of workspaces that this account has access to.
8.2 Create a user account on the server

. users_create , role () username () password () [ supervisor ()]
[ fullname () phonenumber () email () ]
Options
• role - role of the new account, can be one of "interviewer ", or "supervisor ", or "headquarters".
• username - user name of the new account (must be unique on the server).
25
• password - password for the new account, must satisfy the password security requirements
for the server.
• supervisor - name of the supervisor for the new account. Must be specified for the interviewer
accounts, may not be specified for any other accounts. Supervisor with this account must
already exist on the server.
• fullname - (optional) full name of the user of the new account.
• phonenumber - (optional) phone number of the user of the new account.
• email - (optional) email of the user of the new account.
Saved results
• r(UserID) - GUID of the newly created user account
8.3 Get the details of a user account on the server

. users_user guid
Parameters
• guid - GUID of the user.
Saved results
• r(UserId) - account GUID as specified in the query
• r(UserName) - account name corresponding to the specified GUID
• r(Role) - account role in the system
• r(FullName) - full name of the user (if specified)
• r(Email) - contact email of the user (if specified)
• r(PhoneNumber) - contact phone number of the user (if specified)
• r(CreationDate) - date when the account was created
• r(isArchived) - (1=archived; 0=not archived)
• r(isLocked) - (1=locked; 0=not locked)
8.4 Get the details of a supervisor account on the server

. users_supervisor guid
Parameters
• guid - GUID of the supervisor.
Saved results
26
• r(FullName) - full name of the user (if specified)
• r(Email) - contact email of the user (if specified)
• r(PhoneNumber) - contact phone number of the user (if specified)
8.5 Get the details of an interviewer account on the server

. users_interviewer guid
Parameters
• guid - GUID of the interviewer.
Saved results
• r(SupervisorName) - account name of the supervisor of this interviewer
• r(SupervisorId) - account GUID of the supervisor of this interviewer
• r(FullName) - full name of the interviewer (if specified)
• r(Email) - contact email of the interviwer (if specified)
• r(PhoneNumber) - contact phone number of the interviewer (if specified)
• r(isLockedBySupervisor) - (1=locked; 0=not locked)
• r(isLockedByHeadquarters) - (1=locked; 0=not locked)
8.6 Get the list of the supervisor accounts on the server

. users_supervisors [ frame ]
Parameters
• frame - (optional) frame name to save the list of supervisors. If not specified, the current
frame will be used.
Supervisors list frame data structure

strL user_name (for example, "Valentina")
str36 user_id (for example, "978d72ab-82b1-4c7b-a055-cf8922dde4e6")
str40 creation_date (for example, "2020-10-05T15:33:30.317233Z")
byte is_locked (1=locked, 0=not locked)
27
8.7 Get the list of interviewer accounts in a team
. users_interviewers guid frame
Retrives the list of interviewer accounts in a team of a particular supervisor.
Parameters
• guid - GUID of the supervisor/team.
• frame - (optional) name of the frame to be created for the list of the interviewers.
Supervisors list frame data structure
strL user_name (for example, "Natalia")
str36 user_id (for example, "978d72ab-82b1-4c7b-a055-cf8922dde4e6")
str40 creation_date (for example, "2020-10-05T15:33:30.317233Z")
byte is_locked (1=locked, 0=not locked)
8.8 Archive a user account on the server

. users_archive guid
Parameters
• guid - GUID of the user account on the server to be archived.
8.9 Unarchive a user account on the server

. users_unarchive guid
Parameters
• guid - GUID of the user account on the server to be unarchived.
8.10 Obtain a detailed actions log for an interviewer account

. users_actionslog , user () [ framename () from () to () ]
Options
• user - GUID of the interviewer account on the server, for which the detailed actions log is
requested. For example, user(b361cc01-da5d-432e-b926-799f73c7e198).
• framename - (optional) if specified, the detailed actions log will be placed in this new frame,
otherwise the log will be placed into the current frame.
• from - (optional), if specified restricts the detailed actions log to start from this date. Example:
from(2019-01-13T14:48:58Z). NB: if option from() is specified, then option to() must also be
specified.
28
• to - (optional), if specified restricts the detailed actions log to end on this date. Example:
to(2021-01-13T14:48:59Z). NB: if option to() is specified, then option from() must also be
specified.
Detailed actions log frame data structure

str40 time
strL message
29
9 Calendar events
9.1 Add or update a calendar event to an interview

. ce_addupdate interviewkey date timezone text
Parameters
• interviewkey - Interview key for the interview, where the calendar event must be modified,
for example: "12-34-56-78 ".
• date - Date of the calendar event, for example: "2021-04-19 ".
• timezone - Timezone of the calendar event, for example: "EST ".
• text - Text of the note of the calendar event, for example: "All household members will be
available for interviewing".
9.2 Delete a calendar event to an interview

. ce_delete interviewkey
Parameters
30
• interviewkey - Interview key for the interview, where the calendar event must be deleted,
for example: "12-34-56-78 ".
31
10 Workspaces
Workspaces management is a privilege and responsibility. Only some of the methods listed below
are available to the API users. Other methods denoted with an asterisk (*) in the description are
available only to the Survey Solutions administrator. You can switch the account to be used for
API queries already after the initialization of the API client, if necessary:
. s . username =" admin "

. s . password =" Some123Secret "
Note also, that the administrator always has access to all the workspaces on the server.
10.1 Obtain list of workspaces

. workspaces_list , [ frame ()] [ userguid ()] [ includedisabled ]
Options
• frame() - (optional) name of the frame where the list of the workspaces must be saved, for
example: frame("wspaces").
• userguid() - (optional) GUID of the user, if specified the list will include only the workspaces,
to which this user is granted access to.
32
• includedisabled - (optional), if specified the list will also include disabled workspaces; if not
specified, then only enabled workspaces.
Workspaces list frame data structure

string name (for example, "census")
string display_name (for example, "Population Census 2021 ")
string disabled_at_utc (for example, "2020-10-05T15:33:30.317233Z ")
10.2 Get details of a workspace

. workspaces_getdetails name
Parameters
• name - name of the workspace, for example: lfs.
Errors
• Error 5001 is returned if the workspace name is not specified.
Saved results
• r(Name) - specified name of the workspace.
• r(DisplayName) - display name that is attributed to this workspace.
• r(DisabledAtUtc) - blank for workspaces that are not disabled, for disabled workspaces times-
tamp indicating when the workspace was disabled.
10.3 *Create a workspace

. workspaces_update name [ title ]
Parameters
• name - name of the new workspace, for example: lfs.
• title - title of the new workspace, for example: "Labour force survey 2021q4". The title is
optional. The name of the workspace will be used also as a title if the title is not specified.
Errors
33
10.4 *Delete a workspace
. workspaces_delete name , irreversible
Parameters
• name - name of the workspace to be deleted, for example: lfs.
• irreversible - literally the word irreversible. This option is not optional. The user must
understand that the command he issues may cause irreversible damage.
Errors
• Error 198 is returned if the option irreversible is not specified.
10.5 *Obtain workspace status

. workspaces_status name
Parameters
• name - name of the workspace the status of which is to be examined, for example: lfs.
Errors
Saved results
• r(WorkspaceName) - specified name of the workspace, for Example: "census".
• r(WorkspaceDisplayName) - display name that is attributed to this workspace, for example:
"Population Census 2021".
• r(CanBeDeleted) - an flag indicating whether the workspace may be deleted (1) or not (0).
• r(ExistingQuestionnairesCount) - number of questionnaires that are imported to this workspace.
• r(InterviewersCount) - number of interviewer accounts in this workspace.
• r(SupervisorsCount) - number of supervisor accounts in this workspace.
• r(MapsCount) - number of maps in this workspace.
10.6 *Disable a workspace

. workspaces_disable name
Parameters
Errors
34
10.7 *Enable a workspace
. workspaces_enable name
Parameters
Errors
10.8 *Assign users to workspaces

. workspaces_assign mode , users () workspaces ()
The mode can be one of the following:
• add - give the user(s) access to specified workspace(s) in addition to any other workspaces
she currently has access to.
• remove - take away the access permission to the specified workspace(s) leaving any other
access permissions unaffected.
• assign - replace current access permissions with the access only to specified workspaces.
Options
• users() - one or more user account names, for example: frame("SergiyInt"). Multiple account
names must be delimited with spaces, like so: frame("SergiyInt SandraSup").
• workspaces() - one or more names of the workspaces, for example: "agcensus". Multiple
workspace names must be delimited with spaces, like so: "census lfs pricesvy".
Errors
• Error 5001 is returned if the workspaces() is not specified.
• Error 5002 is returned if the users() is not specified.
10.9 Update a workspace title

. workspaces_update name title
Parameters
• title - new title of the workspace, for example: "Labour force survey 2021q4".
35
Errors
• Error 5002 is returned if the workspace title is not specified.
36
11 Photo credits
1. APIs photo by ThisIsEngineering from Pexels.
2. Paper questionnaire photo by Alex Green from Pexels.
3. Ledger photo by Pixabay.
4. Interview photo by Anna Shvets from Pexels.
5. USB flash drive photo by Anete Lusina from Pexels.
6. Maps photo by Andrew Neel from Pexels.
7. Christmas message photo by Jill Wellington from Pexels.
8. Users photo by fauxels from Pexels.
9. Calendar photo by Anete Lusina from Pexels.
10. Workspaces photo by Tima Miroshnichenko from Pexels.
11. Camera photo by Matt Hardy from Pexels.
37
12 HTTP Status codes
Survey Solutions server returns HTTP status codes for the requests it receives. A comprehensive
reference on the HTTP status codes and their interpretation is available for example in Wikipedia.
Below is a short list of most commonly returned status codes for a quick reference.
2xx success:
200 OK
201 Created
202 Accepted
204 No Content
4xx client errors:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
415 Unsupported Media Type
5xx server errors:

500 Internal Server Error
501 Not Implemented
503 Service Unavailable
38
13 Glossary
Short definitions of objects from the Survey Solutions nomenclature are listed below.
Assignment - an electronic order and permission to take part in data collection.

Interview - a collection of answers to the questionnaire obtained from one of the responding
units.
Map - a digital map file in a *.tpk, *.mmpk, or *.tif (Geotiff) formats.
Questionnaire - an electronic template of the questions plan, logic of skips and validations.
Questionnaires do not contain data.
User - a combination of role, user name and password for accessing the Survey Solutions system.
Workspace - logically isolated areas detetermining which user may see and contribute to which
survey/surveys.
39

Survey Solutions Application

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Survey Solutions Application

Uploaded by

Copyright:

Available Formats

Survey Solutions API client for Stata

7 Server notice message 24

8 Users and user accounts 25

12 HTTP Status codes 38

Compatibility with The World Bank Survey Solutions:

• Survey Solutions server: https://mysurvey.solutions/download

Checking Python from Stata.

When you type the following command in Stata:

you should receive a response indicating Python version. For example:

3.8.1 (tags/v3.8.1:1b293b6, Dec 18 2019, 23:11:46) [MSC v.1916 64 bit (AMD64)].

1.1 Create a new API client

• server - URL of the server, for example: "https://demo.mysurvey.solutions"

• password - API account password, for example, "VERY321secret"

2.1 Get a list of questionnaires on the server

Questionnaires list frame data structure

2.2 Get a list of interviews of a questionnaire on the server

• qguid - questionnaire guid identifier.

• qversion - questionnaire version.

Interviews list frame data structure

2.3 Get a questionnaire document in JSON format

• qguid - GUID of the questionnaire as a string, for example:

• saveto - name of the file to be saved, for example: "C:/Temp/qx.json"

• replace - (optional) allow overwriting the output file

2.4 Set audio audit for the survey

• qguid - GUID of the questionnaire as a string, for example:

• value - new mode of audio audit: 1=ON or 0=OFF.

• qguid - GUID of the questionnaire as a string, for example:

3.1 Get details of an assignment

• assignmentid - numeric identifier of the assignment, for example: 1007.

• Error 5001 is returned if the assignmentid is not specified.

3.2 Assign an assignment to a new responsible

• assignmentid - numeric identifier of the assignment, for example: 1007.

• responsiblelogin - account name of the new responsible, for example: "Maryna".

• Error 5001 is returned if the assignmentid is not specified.

• Error 5002 is returned if the responsiblelogin is not specified.

3.3 Archive an assignment

• assignmentid - numeric identifier of the assignment, for example: 1007.

• Error 5001 is returned if the assignmentid is not specified.

3.4 Unarchive an assignment

• assignmentid - numeric identifier of the assignment, for example: 1007.

• Error 5001 is returned if the assignmentid is not specified.

3.5 Close an assignment

• assignmentid - numeric identifier of the assignment, for example: 1007.

• Error 5001 is returned if the assignmentid is not specified.

• number - new quantity for the assignment, for example: 10.

• Error 5002 is returned if the number is not specified.

3.7 Get quantity setting for an assignment

• number - new quantity for the assignment, for example: 10.

3.8 Get audio audit status for an assignment

3.9 Set audio audit status for an assignment

• Error 5002 is returned if the value of audio audit is not specified.

3.10 Get assignment’s history

Assignment history frame data structure

3.11 Create an assignment

• qxguid() - GUID of the questionnaire.

• password() - (optional) password for accessing the web interview online.

• comment() - (optional) a comment to be recorded as an additional instruction regarding this

• protected() - (optional) a space-delimited list of variables to be protected from modification

• data() - (optional) output of the .buildvars method or manually constructed preloading

4.1 Approve an interview by a supervisor

• guid - GUID identifier of the interview to be approved.

• comment - (optional) comment, if specified will be recorded as a comment to the transaction.

4.2 Reject an interview by a supervisor