ODK Central API and Automation Guide

The ODK Central API lets you automate projects, forms, submissions, users, App Users, Entity data, backups, and server workflows. Start with a least-privilege Web User, use session bearer authentication for repeat requests, read and verify data before writing changes, and use OData when the goal is analysis rather than server administration.

This guide is an operational map, not a replacement for the official ODK Central API reference. It helps you choose the right interface and avoid the common mistake of giving a mobile App User or an administrator credential more access than the integration needs.

Choose the right ODK interface

ODK Central exposes several related interfaces:

Need	Interface	Use it for
Manage Central resources	REST API	Projects, users, forms, submissions, attachments, Entity data, and system operations
Submit from a mobile client	OpenRosa endpoints	Form lists, blank form downloads, and submissions from ODK Collect or compatible clients
Analyze current data	OData	Readable submission or Entity data for Power BI, Excel, Tableau, Python, and other clients
Use the web interface	Central frontend	Human review, form testing, submission states, exports, and access management

Use ODK Central with Power BI and Excel when the job is a live report. Use this API workflow when the job is provisioning, synchronization, validation, export automation, or operational tooling.

1. Define the integration's smallest job

Write down the exact operation before creating credentials:

• List projects or forms for a monitoring tool.
• Read submissions for a scheduled data pipeline.
• Download submission attachments.
• Create or update Entity records.
• Provision Web Users or App Users for a controlled onboarding workflow.
• Upload, test, or publish a form through a release process.
• Download a backup or record an export event.

Separate read-only reporting from administrative automation. A script that only reads submissions should not use an administrator identity that can delete forms, change users, or alter project settings.

2. Choose API authentication

ODK Central has different authentication models for Web Users and App Users:

Identity	Authentication	Appropriate access
Web User	Session bearer token or HTTPS Basic authentication	Administrative and project actions allowed by the user's role
App User	App User URL token	OpenRosa form listing, form downloads, and new submissions for assigned forms

For repeat automation, use a Web User session and send its token as a bearer token. ODK's documentation strongly discourages Basic authentication for most repeated requests because it verifies the password on every request. If Basic authentication is unavoidable, use HTTPS and a narrowly scoped account.

Never put a Web User password, session token, or App User token in a public repository, browser bundle, spreadsheet, form, or client-side log. Store it in the integration's secret manager and rotate or revoke it when ownership changes.

3. Start with a read-only health check

Before writing data, make a small request that proves the URL, identity, and permission scope:

1. Call a harmless endpoint such as the project or form listing available to the integration.
2. Confirm the response belongs to the expected Central server.
3. Verify the project and form IDs against a known configuration.
4. Log request timing, status code, and a correlation value without logging credentials or respondent data.
5. Stop if the response is broader than the integration needs.

Use the URL structure consistently. Central resources are nested under a project, and forms are identified by their xmlFormId. A typical submission path follows this shape:

/v1/projects/{projectId}/forms/{xmlFormId}/submissions

Do not infer IDs from a form title. Store the project ID and form ID from a trusted configuration or a verified API response.

4. Read submissions and attachments safely

Submissions are filled forms, and a submission can have versions and multimedia attachments. An integration that downloads only the root record may miss photos, audio, repeat data, or the version information needed to interpret the record.

For each automated extraction:

• Record the project, form ID, form version, extraction time, and filters.
• Preserve the submission instance ID as the stable join key.
• Download attachments deliberately and keep their filenames tied to the source submission.
• Handle pagination or large result sets according to the endpoint documentation and test with a realistic project size.
• Keep the original response or export separate from cleaned analysis tables.
• Treat encrypted submissions as a special case because the API and OData behavior differs from ordinary readable records.

Use the ODK submission review checklist before turning an API extraction into an analysis dataset. It covers receipt checks, review states, repeats, media, and retention.

5. Know when to use OData instead

The REST API is useful for resource operations. OData is usually the better interface for a reporting pipeline that reads current submissions:

• Each form has an OData service with a service document, metadata document, and data documents.
• The root Submissions document represents fields outside repeat groups.
• Repeat data appears in related documents or tables.
• Clients such as Power BI and Excel can refresh the feed.
• Entity Lists also have data available for analysis.

The ODK OData documentation explains the service and metadata paths. Do not use OData as a substitute for a write-capable administrative API, and do not assume encrypted submissions will appear as readable analysis data.

6. Automate Entities with extra care

Entities are shared records that can be created or updated by submissions and accessed by other forms. If your integration touches Entity data:

1. Confirm the Entity List name and property schema.
2. Read the current Entity version before an update when the API requires a base version.
3. Send only the properties the integration owns.
4. Detect and record version conflicts instead of overwriting them silently.
5. Compare automated changes with the submission that caused them.
6. Test offline and concurrent updates in a non-production project.

The ODK Entities and longitudinal workflow explains the form-side design. Treat an API update as part of the same record lifecycle, not as an isolated database edit.

7. Automate form publishing with a release gate

Form automation should separate draft creation from publication:

• Upload or create the draft form.
• Read conversion warnings and fail the pipeline when the warnings are not understood.
• Confirm the form ID, version, attachments, and related Entity schema.
• Run a device or browser test in a controlled project.
• Publish only after the review owner approves the release.
• Notify field teams when the published version changes.

ODK Central creates forms in Draft state by default in the API workflow. Publishing makes the form available for normal collection, and a version conflict can prevent publication. Use the XLSForm validation checklist and the ODK Central form release checklist before letting an automated pipeline publish a form.

8. Debug 401 and 403 responses

The status code usually tells you which layer to inspect:

Status	Meaning	First check
401 Unauthorized	Credentials are missing, invalid, or expired	Token format, session lifetime, server URL, and secret loading
403 Forbidden	The identity is valid but lacks the required permission or scope	Web User role, project assignment, form access, or App User limits
404 Not Found	The resource path or identifier is wrong, or the identity cannot see it	Project ID, xmlFormId, endpoint version, and accessible scope
409 Conflict	The requested change collides with the current resource state	Form version, Entity base version, or duplicate resource

Do not “fix” a 403 by granting administrator access immediately. Read the role and assignment model, create the smallest useful permission, and test again with a non-production project.

9. Record operations for audit and recovery

An integration should make its own activity explainable:

• Which account or service initiated the request?
• Which project, form, submission, or Entity did it touch?
• What changed and why?
• What source submission, form version, or Entity version caused the change?
• What was the response status and retry result?
• Can the operation be replayed or reversed safely?

Retain API configuration and output according to the study's data policy. For server recovery, use the ODK Central backup checklist. For field access and account scope, use ODK Central user management.

SurveyLoopr can host the ODK Central server, but your team remains responsible for integration credentials, code, permission reviews, data retention, and the consequences of automated writes. Start with a read-only integration before adding form publication or Entity updates.

Deploy a managed ODK server

Review the submission workflow