Quickstart
Take one SPSS survey from file to findings. Each step shows the plain HTTP request and the Python SDK call; choose a language once and every example follows.
1.Set up your environment
You need an API key with the datasets:write, surveyguard:write and surveyguard:read permissions; see API keys. Keep the key in an environment variable named CM_API_KEY.
The Python SDK is an unpublished preview installed from source; see Python SDK. Nothing on this page runs for you: reading it never starts a billable run.
export CM_API_BASE="https://dev.crowdmines.ai/api/customer/v1"
# Set CM_API_KEY securely in your environment; do not paste it into source code.
# Use the same environment where you created your key.
export CM_PROJECT_ID="YOUR_PROJECT_ID"
export CM_BATCH_REQUEST_ID="YOUR_UNIQUE_BATCH_ID"
2.Upload an SPSS survey
Survey Guard accepts .sav files only. Request an upload, send the file to the storage URL you get back with the headers you get back, complete the upload, then create a project from the dataset.
The storage request must not carry your API key. Upload links expire; do not log or share them. If you abandon an upload, cancel it with DELETE /datasets/uploads/{upload_id}.
Save the project ID as CM_PROJECT_ID. Already have a saved project? Skip to the next step.
# Python 3, standard library only. Uploads a file; does not run checks.
import json, os, pathlib, urllib.request
base = os.environ["CM_API_BASE"].rstrip("/")
key = os.environ["CM_API_KEY"]
file = pathlib.Path("survey.sav")
def api(method, path, body=None):
data = None if body is None else json.dumps(body).encode()
request = urllib.request.Request(base + path, data=data, method=method,
headers={"Authorization": "Bearer " + key,
"Content-Type": "application/json"})
with urllib.request.urlopen(request, timeout=120) as response:
return json.load(response)
intent = api("POST", "/datasets/uploads", {
"filename": file.name, "size_bytes": file.stat().st_size,
"purpose": "dataset", "tool_key": "surveyguard"})
# Only the returned storage headers go to storage. Never send CM_API_KEY.
with file.open("rb") as source:
request = urllib.request.Request(intent["upload_url"], data=source,
method=intent["method"], headers={**intent["headers"],
"Content-Length": str(file.stat().st_size)})
with urllib.request.urlopen(request, timeout=300) as response:
response.read()
dataset = api("POST", "/datasets/uploads/" + intent["upload_id"] + "/complete")
project = api("POST", "/surveyguard/projects", {
"dataset_id": dataset["dataset_id"], "name": "Survey quality review"})
print("Project ID:", project["id"])
3.Review the checks
Read the configuration’s draft, issues and revision. Check the column mappings, the selected checks and the AI settings, and resolve every issue before you run. You can also set the project up in the Survey Guard app.
Saving requires the revision you read, so one update cannot silently overwrite another. Keep the latest revision: the batch needs it.
curl --fail-with-body "$CM_API_BASE/surveyguard/projects/$CM_PROJECT_ID/configuration" \
-H "Authorization: Bearer $CM_API_KEY" > configuration.json
# Review the draft, issues and revision before submitting a run.
# To save edits, create configuration-update.json with:
# {"expected_revision": <revision you read>, "draft": <your edited draft>}
curl --fail-with-body -X PUT \
"$CM_API_BASE/surveyguard/projects/$CM_PROJECT_ID/configuration" \
-H "Authorization: Bearer $CM_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @configuration-update.json
4.Submit a batch
A batch holds 1–10 distinct projects. Give each item a unique item_id and its current configuration revision.
Before sending, save the exact request body and a unique Idempotency-Key. If the response is lost, resending both recovers the same batch instead of starting a second one.
A 202 response means the batch was accepted, not that the checks passed. Save the batch_id.
# Requires jq. Use the latest revision returned by GET or PUT configuration.
export CM_CONFIGURATION_REVISION="YOUR_LATEST_REVISION"
jq -n --arg project "$CM_PROJECT_ID" \
--argjson revision "$CM_CONFIGURATION_REVISION" \
'{items: [{item_id: "survey-a", project_id: $project,
configuration_revision: $revision}]}' > batch.json
# This starts processing and can consume credits / incur AI charges.
curl --fail-with-body "$CM_API_BASE/surveyguard/batches" \
-H "Authorization: Bearer $CM_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $CM_BATCH_REQUEST_ID" \
--data-binary @batch.json
5.Track progress and read results
Poll the batch every 5–10 seconds until its status is succeeded, partial_failure or failed. Inspect every item: one batch can hold both successful and failed surveys.
A result contains respondent flags, scores, evidence and coverage. Read the skipped, partial and failed checks as well as the flags; a completed run does not mean every check applied.
Download links are short-lived. Ask for a new one if yours expires, and keep result files and links private.
export CM_BATCH_ID="BATCH_ID_FROM_SUBMISSION"
curl --fail-with-body "$CM_API_BASE/surveyguard/batches/$CM_BATCH_ID" \
-H "Authorization: Bearer $CM_API_KEY"
# After an item succeeds, use its run_id.
export CM_RUN_ID="SUCCEEDED_ITEM_RUN_ID"
curl --fail-with-body "$CM_API_BASE/surveyguard/runs/$CM_RUN_ID" \
-H "Authorization: Bearer $CM_API_KEY"
# Keep the signed link private; never send the API key to storage.
RESULT_URL=$(curl --fail-with-body \
"$CM_API_BASE/surveyguard/runs/$CM_RUN_ID/result-link" \
-H "Authorization: Bearer $CM_API_KEY" | jq -er '.url')
curl --fail-with-body "$RESULT_URL" --output result.json
Next
Make the integration safe to leave unattended with Errors and retries, or look up any field in the HTTP reference.