*! version 1.6.4 18jun2026

Title

suso -- Client for the Survey Solutions (SuSo) REST API

Syntax

Configure the connection (once per session):

suso config , server(url) workspace(name) user(apiuser)
password(pw) [config_options]

Run a command of the form:

suso noun verb [, options]

Quick utilities (no verb):

suso ping

suso doctor

suso login

suso config [, show|clear]

suso examples

suso endpoints

suso about

suso raw path [, method(verb) query(string) body(json) todata ...]

where noun is one of assignment, interview, questionnaire,
export, user, supervisor, interviewer, workspace,
maps, settings, or statistics; and verb is the action (for example,
list, get, create). See Subcommands.

Most list/get commands that return rows load them into memory as the
current dataset, replacing any unsaved data. Scalar responses are returned in
r(); see Stored results.

Description

suso is a complete Stata client for the World Bank
Survey Solutions REST API
(API v1 and v2). It lets you script fieldwork operations that otherwise require
the web interface: list and inspect assignments and interviews; approve, reject,
comment on, reassign and delete interviews; create and manage assignments and
users; start, monitor and download data exports; and administer workspaces and
server settings - all from Stata do-files.

suso talks to the server through a small, dependency-free Java backend
(suso.jar) using Stata's javacall. The Java layer performs the
HTTPS requests (with proper PATCH/PUT/DELETE, optional proxy,
streaming file downloads, and redirect handling) and hands results back to
Stata. You never call Java directly; the .ado interface is the whole API.

List endpoints page through results automatically and load them as a Stata
dataset; commands that fetch a single object expose its fields in r().
Operations that change or remove data on the server are guarded
(see Destructive operations).

Setup

Configure the server and workspace once per session. user() and
password() are optional - if you omit them, suso prompts
for the user name and a masked password the first time a command contacts the
server (or run suso login to enter them up front). Use a dedicated
API user, not Headquarters or Administrator credentials.

. suso config , server("https://your-server") workspace("myws")

. suso ping

To supply credentials non-interactively, add user() (and optionally
password()); safer still, set the SUSO_PASSWORD environment variable
before launching Stata so the password never enters your command history.
Credentials are kept for the session only.

Optionally pin a default questionnaire so you can omit guid()/qver():

. suso config , guid("76732117-1b19-4c82-bd39-1e34a781a2e9") qver(11)

Settings live in global macros for the session only; nothing is written to
disk except the optional audit log. Review the current settings with
suso config , show (the password is masked) and clear them with
suso config , clear. Verify the Java runtime and the location of
suso.jar with suso doctor.

Configuration options

For suso config:

config_option

server(url) base server URL, e.g. https://demo.mysurvey.solutions

workspace(name) workspace short name (path segment), e.g. primary

user(name) API user name

password(pw) API user password

token(t) use a bearer token instead of user/password

auth(type) authentication scheme: basic (default) or bearer

jar(path) full path to suso.jar (only if not on the adopath)

guid(id) default questionnaire GUID for later commands

qver(#) default questionnaire version

proxyhost(h) proxy host (corporate networks)

proxyport(#) proxy port

proxyuser(u) proxy user

proxypass(p) proxy password

insecure skip TLS certificate verification (use with care)

noinsecure re-enable TLS verification

conntimeout(ms) connection timeout in milliseconds (default 30000)

readtimeout(ms) read timeout in milliseconds (default 300000)

maxrows(#) safety cap on rows fetched by paginated lists (default 100000)

auditfile(path) append destructive actions to this log file

show display the current configuration (password masked)

clear clear all session configuration

Common options

guid(id) and qver(#) identify a questionnaire. They may be omitted
when a default has been set with suso config , guid() qver().

all on a list command fetches every matching record by paging
through the server; without all only the first page is returned.
See Pagination.

saving(filename) (with replace) writes a downloaded artifact
(export archive, interview/questionnaire PDF, statistics file). Relative paths
resolve against the Stata working directory (pwd).

confirm is required to proceed with most destructive verbs;
see Destructive operations.

verbose prints the HTTP method, URL and status for the request -
the first thing to add when a call behaves unexpectedly.

Subcommands

Connection and utilities

suso ping test connectivity and credentials

suso doctor check Java runtime and locate suso.jar

suso login prompt for the API user and password (masked)

suso config set or show/clear the session configuration

suso about show package version

suso examples print copy-paste recipes

suso endpoints print the full command list

suso raw path call any endpoint not wrapped below

assignment

list assignments; filters searchby() responsible() supervisor() order() archived guid() qver() all

get id() one assignment

history id() assignment history (start() length())

quantitysettings id() quantity settings for an assignment

create responsible() create an assignment (quantity() email() password() webmode audio comments() targetarea() identifying())

assign id() responsible() reassign an assignment

quantity id() n() change interview quantity

close id() close an assignment

archive id() archive an assignment

unarchive id() unarchive an assignment

audio id() [on off] get or set audio recording

targetarea id() area() set the target area

interview

list interviews; filters status() guid() qver() id() all

get id() interview answers (loaded as data)

stats id() interview statistics

history id() interview event history (loaded as data)

pdf id() saving() download the interview PDF

approve id() supervisor approve (comment())

reject id() supervisor reject (comment() responsible())

hqapprove id() HQ approve

hqreject id() HQ reject

hqunapprove id() HQ unapprove

assign id() assign to an interviewer (responsible()|responsibleid()|responsiblename())

assignsupervisor id() assign to a supervisor

comment id() question() comment() comment on a question

commentbyvar id() variable() comment() comment by variable (rostervector())

delete id() delete an interview (destructive)

questionnaire

list questionnaires on the server (all)

get details for guid() qver()

document saving() download the questionnaire document (PDF)

interviews interviews for a questionnaire (all)

audio [get on off] get/set audio recording for a questionnaire

criticality [get level()] get/set criticality level

export

list existing export jobs (type() istatus() estatus() hasfile all)

start type() start an export (istatus() guid() qver() from() to() meta|nometa paradatareduced)

status id() poll an export job's status

download id() saving() download a completed export archive; add unzip (or unzipw(pw) for password-protected archives, unzipto(dir) for the target folder) to extract it

get type() saving() one-shot: start, show progress, and auto-download when complete (accepts unzip/unzipw()/unzipto() and all start filters)

cancel id() cancel/delete an export job (destructive)

type() is one of STATA, SPSS, Tabular, Binary,
DDI, Paradata. See Export workflow.

maps (uploads/deletes via the GraphQL endpoint; see Maps)

list list maps on the server (workspace())

upload file() upload a map file (name() to override the stored name)

delete name() delete one map (destructive)

deleteall delete every map in the workspace (destructive; dry-run unless confirmed)

Backup

suso backup , dir(folder) [types(STATA Paradata ...) istatus(All) nometa
pollsecs(10) jobtimeout(3600) noexports noquestionnaires noworkspace]

Archives a whole workspace into folder using the existing verbs: a questionnaire
list (questionnaires_list.dta) plus one JSON document per version; one export zip
per questionnaire-version per types() entry (start -> poll -> download, with
empty jobs skipped and per-job failures tolerated); and assignments.dta +
supervisors.dta. Returns r(ok), r(skipped), r(failed). Your current
data is preserved/restored. Example: suso backup , dir("C:/archive/srilanka") types(STATA Paradata).

assign name() user() give an interviewer access to a map

unassign name() user() remove an interviewer's access

user, supervisor, interviewer

user get id() user details

user create role() username() password() create a user (fullname() phone() email() supervisor())

user archive id() archive a user

user unarchive id() unarchive a user

supervisor list supervisors (all)

supervisor get id() supervisor details

supervisor interviewers id() interviewers under a supervisor (all)

interviewer get id() interviewer details

interviewer actionslog id() interviewer action log (start() end())

workspace, settings, statistics

workspace list workspaces (includedisabled)

workspace get|status name() workspace details/status

workspace create name() displayname() create a workspace

workspace update name() displayname() rename a workspace

workspace enable|disable name() enable/disable a workspace

workspace delete name() delete a workspace (destructive)

workspace assign userids() workspaces() assign users to workspaces (mode() supervisor())

settings get server global notice

settings set message() set the global notice

settings clear clear the global notice

statistics questionnaires questionnaires available for reporting

statistics questions reportable questions for guid() qver()

statistics report question() tabulation report (exporttype() saving() query())

Most workspace verbs require admin rights and accept usews to act
against the configured workspace context. See Administration
below for worked examples of workspace, settings and statistics.

Pagination

list commands fetch only the first page by default. Add all to
page through and return every matching record. suso learns the server's
effective page size automatically (Survey Solutions caps some lists, e.g.
interviews at 40 per page) and keeps requesting pages until the reported total
is reached, so all is reliable even when the server returns fewer rows than
requested. The maxrows() configuration value is a safety ceiling on the
total number of rows a single all call will load.

Export workflow

Exporting data is three steps: start, poll status until it reports
Completed, then download. To do all three at once, use the one-shot
export get (below) - it starts the job, prints progress as it
climbs, and downloads automatically the moment it hits 100%.

. suso export start , type(STATA) qver(11) istatus(ApprovedBySupervisor)

. suso export status , id(`=r(jobid)')

. suso export download , id(`=r(jobid)') saving("data.zip") replace unzip

Or the same end to end in one command (no manual polling):

. suso export get , type(STATA) qver(11) istatus(ApprovedBySupervisor) saving("ses_v11.zip") replace

. suso export get , type(STATA) qver(11) saving("ses_v11.zip") replace unzipw("pw") unzipto("O:/.../extracted")

get takes the same filters as start (type(), guid(),
qver(), istatus(), meta|nometa) plus the extraction
options of download. Polling cadence is pollsecs() (default 10s) and it
gives up after jobtimeout() (default 3600s). If the completed job has no data
for the filter, nothing is downloaded and r(status) is NoFile. Returns
r(saved), r(jobid), r(status) and (when extracting)
r(unzipped)/r(unzipdir).

Add unzip to extract the archive after download (into a folder named after the zip, or unzipto(dir)). Survey Solutions can password-protect exports; for those, use unzipw(password). Extraction is done by the bundled Java backend and supports the traditional ZipCrypto scheme SuSo uses, so no external unzip tool is required. r(unzipped) and r(unzipdir) report the result.

Extraction variants:

// plain archive -- extract beside the zip

. suso export download , id(`=r(jobid)') saving("ses_v11.zip") replace unzip

// password-protected archive

. suso export download , id(`=r(jobid)') saving("ses_v11.zip") replace unzipw("yourpassword")

// password-protected, extracting to a chosen folder

. suso export download , id(`=r(jobid)') saving("ses_v11.zip") replace unzipw("pw") unzipto("O:/.../2026-06-17/extracted")

unzipw() implies unzip, so you need not give both. The unzipw()
password is the archive password set on the export, which is different from
your API password().

start returns the job id in r(jobid). A questionnaire version
is required (the API identifies a questionnaire as guid$version); set
qver() or a default via suso config. Immediately after a job reports
Completed the file endpoint can briefly return HTTP 403 while the archive
is finalized - simply retry download (or poll status once
more). Downloads follow the server's redirect to storage and stream straight to
saving().

Maps (GraphQL)

Unlike the rest of suso, map management uses Survey Solutions' GraphQL
endpoint (/graphql), not the REST API. The maps subcommands wrap this
for you, so the workflow is the same as any other suso command:

. suso maps list

. suso maps upload , file("C:/maps/region.tpk")

. suso maps assign , name("region.tpk") user("FieldInt01")

. suso maps delete , name("region.tpk") confirm

upload sends a .zip archive (containing a complete shapefile family
.shp+.dbf+.shx+.prj, and/or .tif/GeoTIFF or .tpk
basemaps) as a GraphQL multipart upload; one archive may carry several maps. list loads the maps into a
dataset (file name, size, import date, uploader). delete is irreversible and needs confirm. deleteall wipes the
whole library: by default it only lists what would go (a dry run); to actually
delete you confirm by typing the workspace name, e.g. suso maps deleteall ,
iknowthis(srilankainf). It is throttled (sleep() ms between deletes,
default 200) and tolerant of per-map failures, reporting r(deleted)/r(failed). assign/unassign control which interviewers
can download a given map to their tablet. If your server expects a workspace
argument on a map operation and rejects a call, the GraphQL error message is
shown verbatim so you can adjust.

Administration: workspace, settings, statistics

These verbs administer the server, not survey data. Most default to the
server root rather than your configured workspace; add usews only if
your deployment scopes them under the workspace path.

Who can run what. Permission is set by the account in suso config , user().
Running an admin-only verb with a plain API user returns HTTP 401/403 from the server.

Any API user - read workspace list, workspace get, workspace status, settings get, and all statistics verbs

Admin only - write workspace create, update, enable, disable, delete, assign; and settings set / clear

Two of the admin-only verbs - workspace disable and
workspace delete - are also destructive and carry extra
guards (see Destructive operations).

Read (any API user)

Workspaces. list loads a dataset; get and status return values in r():

. suso workspace list , includedisabled

. suso workspace get , name("srilankainf") // r(name), r(displayname)

. suso workspace status , name("srilankainf")

status reports, and returns, r(canbedeleted) alongside
r(existingquestionnairescount), r(supervisorscount),
r(interviewerscount) and r(mapscount) - use it before a
delete to see what a workspace still holds.

Settings. get returns the server login banner in r(message):

. suso settings get

Statistics are server-side tabulations, with no microdata pulled:

. suso statistics questionnaires // dataset of reportable questionnaires

. suso statistics questions , guid(<guid>) qver(3) // reportable questions

. suso statistics report , question(q14_sector) guid(<guid>) qver(3)

. suso statistics report , question(q14_sector) guid(<guid>) qver(3) exporttype(xlsx) saving("sector_tab.xlsx") replace

report needs the question's variable name (for example q14_sector),
not a guid; it loads the tabulation into a dataset, or writes it to a file with
saving() (exporttype() = csv, tab or xlsx). Pass any
extra report parameters verbatim with query(). If guid()/qver()
are omitted they fall back to suso config. For case-level data use
suso export or suso backup instead.

Admin only (write)

These require an administrator account. A plain API user cannot run them.

Create / rename / enable. displayname() is the human-readable label:

. suso workspace create , name("ises2026") displayname("ISES Sri Lanka 2026")

. suso workspace update , name("ises2026") displayname("ISES SL 2026 (field)")

. suso workspace enable , name("ises2026")

Disable (reversible, but destructive - blocks the workspace) requires confirm:

. suso workspace disable , name("ises2026") confirm

Delete (irreversible) is the most guarded command: retype the name in
iknowthis(), and it runs a pre-flight status check that refuses a
non-empty workspace unless you add force:

. suso workspace delete , name("ises2026") iknowthis("ises2026")

. suso workspace delete , name("ises2026") iknowthis("ises2026") force

Assign maps users to workspaces. userids() and workspaces() are
space-separated lists; mode() is Assign (replace; the default),
Add or Remove; supervisor() attaches interviewers to a
supervisor id:

. suso workspace assign , userids("11111111-id1 22222222-id2") workspaces("ises2026")

. suso workspace assign , userids("33333333-id3") workspaces("ises2026") mode(Add) supervisor("99999999-sup")

Settings. set writes the server-wide login banner; clear removes it:

. suso settings set , message("Fieldwork freeze 20-22 Jun for QC.")

. suso settings clear

Destructive operations

Verbs that delete or irreversibly change server state - for example
interview delete, export cancel, workspace delete -
require the confirm option to proceed and are recorded in the audit log if
auditfile() is configured. workspace delete additionally requires
iknowthis() matching the workspace name. This guard is deliberate; review
the target before adding confirm in a do-file.

Stored results

suso commands are rclass. After any command:

Scalars and macros

r(http) HTTP status code of the last request

r(nobs) number of rows loaded (list/get-as-data commands)

r(totalcount) server-reported total for a paginated list

r(saved) path written by a download/saving() command

r(bytes) bytes written by a download

r(jobid) export job id (after export start)

r(field) each scalar field of a single-object response, lowercased

For a single-object response (for example export status or
interview stats), each top-level scalar field of the JSON is returned as
r(field) with the field name lowercased (e.g. r(exportstatus),
r(progress)). Rows are loaded as the current dataset and are not duplicated
in r().

Examples

Every example below is a real command. guid is a questionnaire id and qver
its version; set them once with suso config , guid() qver() or pass them per
command. List/browse verbs replace the data in memory; single-record verbs fill r().

1. Set up and test the connection

You only need server() and workspace(). user() and password()
are optional: if you omit them, suso asks for the user name and a masked
password the first time a command contacts the server (or run suso login to enter
them up front). So the minimal setup is just:

. suso config , server("https://demo.mysurvey.solutions") workspace("primary")

. suso ping // prompts for user + password (masked), then checks auth

You may still supply them non-interactively with user() / password(), or
- safer, keeping the password out of your command history - set the
SUSO_PASSWORD environment variable before launching Stata:

. suso config , server("https://demo.mysurvey.solutions") workspace("primary") user("API_USER")

. suso login // enter / replace credentials at a masked prompt anytime

. suso doctor // Java/JVM check + which suso.jar is in use

. suso config , show // review current settings (password masked)

2. Pull lists into a Stata dataset

Add all to fetch every page (auto-paginated):

. suso assignment list , all

. suso assignment list , responsible("FieldInt01") guid(<guid>) qver(11)

. suso interview list , status(Completed) all

. suso questionnaire list , all

. suso supervisor list , all

. suso supervisor interviewers , id(<supervisor-id>) all

. suso export list

3. Inspect one record (values land in r())

. suso assignment get , id(123)

. suso interview get , id(2e0ec4fa-9ec7-4849-ba6e-1e8a18995457)

. suso interview stats , id(2e0ec4fa-9ec7-4849-ba6e-1e8a18995457)

. return list // see everything the call returned

4. Interview QC workflow

Approve / reject (HQ variants escalate to headquarters):

. suso interview approve , id(<uuid>) comment("looks good")

. suso interview reject , id(<uuid>) comment("GPS off-square; please revisit")

. suso interview hqapprove , id(<uuid>)

. suso interview hqreject , id(<uuid>) comment("inconsistent roster")

Comment on a specific question, by question id or by variable name:

. suso interview comment , id(<uuid>) question(<question-id>) comment("verify units")

. suso interview commentbyvar , id(<uuid>) variable(q14_sales) comment("seems too high")

. suso interview commentbyvar , id(<uuid>) variable(emp_name) rostervector(2) comment("typo")

Reassign, save the PDF, or delete (delete needs confirm):

. suso interview assign , id(<uuid>) responsible("FieldInt07")

. suso interview assignsupervisor , id(<uuid>) responsible("Sup02")

. suso interview pdf , id(<uuid>) saving("iv.pdf") replace

. suso interview delete , id(<uuid>) confirm

5. Assignments

. suso assignment create , responsible("FieldInt01") guid(<guid>) qver(11) quantity(3)

. suso assignment assign , id(123) responsible("FieldInt09") // reassign

. suso assignment quantity , id(123) n(5) // change target count

. suso assignment audio , id(123) on // audio audit on/off

. suso assignment close , id(123)

. suso assignment archive , id(123) confirm // destructive

6. Questionnaires

. suso questionnaire document , guid(<guid>) qver(11) saving("q.json") replace

. suso questionnaire interviews , guid(<guid>) qver(11) all // interviews for this version

. suso questionnaire audio , guid(<guid>) qver(11) on // require audio audit

. suso questionnaire criticality , guid(<guid>) qver(11) get

7. Export data

One-shot - start, watch progress, and download automatically when done:

. suso export get , type(STATA) guid(<guid>) qver(11) istatus(ApprovedBySupervisor) saving("ses_v11.zip") replace

Same, but unzip on arrival (the archive password is unzipw(), not your API password):

. suso export get , type(STATA) qver(11) saving("ses_v11.zip") replace unzipw("pw") unzipto("O:/ises/extracted")

Or drive the three steps yourself (other types: Tabular, SPSS, Binary, Paradata, DDI):

. suso export start , type(SPSS) guid(<guid>) qver(11) istatus(All)

. suso export status , id(`=r(jobid)')

. suso export download , id(`=r(jobid)') saving("data.zip") replace unzip

8. Maps (GraphQL)

. suso maps list // all maps in the workspace (auto-paginated)

. suso maps upload , file("colombo_grid.zip") // .zip of a shapefile family, or a .tif/.tpk

. suso maps assign , name("colombo_grid.tif") user("SL_Colombo_Ali01")

. suso maps delete , name("old_grid.tif") confirm // one map (destructive)

Wipe the whole map library - dry-run first, then confirm by typing the workspace name:

. suso maps deleteall // DRY RUN: lists what would go, deletes nothing

. suso maps deleteall , iknowthis("srilankainf") // actually deletes all

9. Users (admin account required)

. suso user get , id(<user-id-or-name>)

. suso user create , role(Interviewer) username("SL_Colombo_Ali01") password("Strong#123") fullname("Ali Khan")

. suso interviewer actionslog , id(<interviewer-id>) start("2026-06-01") end("2026-06-17")

. suso user archive , id(<user-id>) confirm // destructive

10. Workspaces (admin); see help suso##admin

. suso workspace list , includedisabled

. suso workspace status , name("srilankainf") // counts + r(canbedeleted)

. suso workspace create , name("ises2026") displayname("ISES Sri Lanka 2026")

. suso workspace disable , name("ises2026") confirm

. suso workspace delete , name("ises2026") iknowthis("ises2026") // strongest guard

. suso workspace assign , userids("id1 id2") workspaces("ises2026") mode(Add) supervisor("sup-id")

11. Server settings and statistics

. suso settings get

. suso settings set , message("Fieldwork freeze 20-22 Jun for QC.") // admin

. suso settings clear

. suso statistics questionnaires

. suso statistics questions , guid(<guid>) qver(11)

. suso statistics report , question(q14_sector) guid(<guid>) qver(11) exporttype(xlsx) saving("tab.xlsx") replace

12. Back up an entire workspace

One command archives questionnaires, exports (per type), and assignments/users:

. suso backup , dir("C:/archive/srilanka")

. suso backup , dir("C:/archive/srilanka") types(STATA Paradata) jobtimeout(7200)

13. Reach any endpoint with suso raw

. suso raw /api/v1/settings/globalnotice // GET, flatten to r()

. suso raw /api/v1/assignments , query(Limit=5&Offset=0) todata arraykey(Assignments)

. suso raw /api/v1/interviews/<uuid> , method(DELETE) allowdestructive

Tip: add verbose to any command to print the exact request it sends.
suso examples prints a short version of these inside Stata.

Requirements

Stata 14.2 or later and a Java 11+ runtime. Stata ships a bundled Java; confirm
with suso doctor. The Java backend suso.jar is installed alongside
suso.ado and is found automatically on the adopath; if you keep it
elsewhere, point to it with suso config , jar(path).

suso requires a Survey Solutions API user (not Headquarters or
Administrator credentials). All settings are session-only globals; only the
optional audit log is written to disk.

Author

Attique Ur Rehman, Economist

The World Bank - Development Economics (DEC), Enterprise Surveys

Email: attique@worldbank.org

Web: https://sites.google.com/view/attique-ur-rehman

Acknowledgments

Thanks to Fahad Mirza (World Bank / CERP,
github.com/fahad-mirza) for his insights
and guidance, and for his self-contained Stata tooling (sparkta,
wordcloud2) that helped shape this package's design.

Built on the World Bank
Survey Solutions platform and its
public REST API. This package is an independent client and is not an official
Survey Solutions product.

Also see

Online: Survey Solutions API documentation

Help: javacall, import, shell