canonical: https://jentic.com/apis/getodk.org/getodk # Getodk ODK Central API ODK Central is the server-side component of the Open Data Kit ecosystem, used for managing forms, submissions, and field-data-collection users in offline-friendly mobile data collection workflows. The API exposes 32 endpoints covering session-based authentication, project and form lifecycle management, XML and submission ingestion, and assignments for App Users that operate ODK Collect on devices in low-connectivity environments. It is the backbone for humanitarian, public-health, and field-research deployments that need a self-hosted, auditable form server. ## For AI agents Manage ODK Central projects, XLSForms, submissions, and field App Users for humanitarian and field-data-collection workflows from a self-hosted server. ## Scope Does not handle survey distribution to consumers, panel recruitment, or analytics dashboards - use for managing ODK Central projects, forms, and field submissions only. ## Capabilities - Authenticate against ODK Central by creating a bearer-token session and revoking it on logout - Provision projects and upload XForms or XLSForms for distribution to ODK Collect devices - Retrieve submission instances with their attachments and the parsed form schema fields - Create and manage App Users that log into ODK Collect for offline data collection - Assign roles to actors at the site or project level for fine-grained access control - Update or soft-delete forms while preserving prior submissions for audit trails ## Use cases ### Humanitarian field data collection ODK Central powers offline-first survey deployments for NGOs, public health teams, and disaster-response organisations. Fieldworkers collect submissions through ODK Collect on Android devices, syncing to the Central server when connectivity is available. The API lets back-office systems pull submissions, attachments, and parsed schema fields for downstream analysis without writing custom XForm parsers. Example prompt: Upload an XLSForm titled 'household-census-2026' to project 12 and confirm the form moves to the open state ### Submission pipeline to a data warehouse Research teams use ODK Central as a staging server then ETL submissions into PostgreSQL, BigQuery, or a managed data warehouse. The /projects/{projectId}/forms/{xmlFormId}/submissions endpoint supports paginated retrieval, and the fields endpoint returns the parsed schema so the pipeline can map XForm types to warehouse columns automatically. Example prompt: List all submissions for form 'water-quality-v3' in project 7 created after 2026-06-01 and write them as JSON to S3 ### Field user provisioning at scale Programmes onboarding hundreds of enumerators script user creation through the API rather than the web console. Combine POST /users for back-office staff with App User creation per project for fieldworkers, then assign role-scoped access so each enumerator only sees the forms they should collect against. Example prompt: Create 50 App Users in project 4 named 'enumerator-001' through 'enumerator-050' and download their access tokens ### AI agent triage of new submissions An AI agent connected through Jentic polls ODK Central for new submissions, parses media attachments such as photos or audio against a vision or speech model, and writes structured tags back into a downstream CRM. Jentic handles the bearer-session lifecycle so the agent never holds long-lived credentials. Example prompt: Fetch the 10 most recent submissions on form 'site-inspection' in project 3, run vision analysis on each photo attachment, and post the labels back as comments ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /sessions | Create a new bearer-token session | | GET | /projects | List projects | | POST | /projects/{projectId}/forms | Upload an XLSForm or XForm | | GET | /projects/{projectId}/forms/{xmlFormId}/submissions | List form submissions | | GET | /projects/{projectId}/forms/{xmlFormId}/fields | Get parsed form schema fields | | POST | /users | Create a back-office user | ## Key resources - **Sessions** — Bearer-token session creation and termination for authenticating actors - **Users** — Manage back-office actors, including password reset and current-user lookup - **Projects** — Top-level container for forms, App Users, and assignments - **Forms** — XForm and XLSForm definitions plus their parsed schema fields - **Submissions** — Submitted form instances with attachments and edit history - **App Users** — Tokens used by ODK Collect on field devices for offline data capture ## Why Jentic - **Setup:** Wiring ODK Central by hand means resolving your self-hosted host, opening a session for the bearer token, and threading the project id and form id through the submission paths yourself. Through Jentic you install once, import the ODK Central API from the API Directory, store the credential once, and your agent calls it. - **Permission scoping:** ODK Central puts the project id in the URL path (/projects/{projectId}/forms/...), so a rule can pin your agent to one project: it reads forms, submissions, and fields there and touches no other project. You choose the operations it may call, so creating a user is not included unless you add it. - **Credential handling:** Your ODK Central credential is stored once, encrypted, by your own Jentic One instance and exchanged for a scoped session token at execution time. The raw password never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list ODK submissions' or 'read a form's fields', and Jentic returns the matching ODK Central operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **KoboToolbox API** — Hosted humanitarian data collection platform built on the same XForm standard - **SurveyMonkey API** — Web-first survey platform with a richer respondent UI but no offline collection - **Typeform API** — Conversational web forms that can complement field-collected ODK data with public-facing surveys ## FAQ ### What authentication does the ODK Central API use? ODK Central uses session bearer tokens. Call POST /sessions with email and password to receive a token, then send it as Authorization: Bearer in subsequent requests. Through Jentic the credential is stored encrypted in the vault and a scoped token is injected at execution time so the raw password never enters agent context. ### Can I upload XLSForms with the ODK Central API? Yes. POST /projects/{projectId}/forms accepts XLSForm and XForm payloads, and Central converts XLSForms to XForms server-side. Use PATCH on the same form path to update metadata such as state without re-uploading the definition. ### What are the rate limits for the ODK Central API? The OpenAPI spec does not declare hard rate limits. ODK Central is typically self-hosted, so practical limits depend on your deployment's CPU and database tier. For large submission pulls, paginate using the standard ODK Central paging parameters rather than fetching everything at once. ### How do I retrieve submissions for a form through Jentic? Search Jentic for 'list ODK Central submissions', load the GET /projects/{projectId}/forms/{xmlFormId}/submissions schema, then execute with the project and form identifiers. Jentic handles the bearer-token refresh between calls. ### Is the ODK Central API free? ODK Central itself is open-source under Apache 2.0 and you can self-host at no licence cost. Hosted Central installations from third-party providers price by submissions or active forms - check your provider for specifics. ### Can I create App Users for offline ODK Collect devices via the API? Yes. POST to the App Users endpoint under a project to mint a token that ODK Collect can use to download forms and submit data. Each App User is scoped to a single project and can be revoked individually without affecting other field devices. ### Can I limit what my agent is allowed to do with the ODK Central API? Yes. Because ODK Central puts the project id in the URL path (/projects/{projectId}/forms/...), a rule in your self-hosted Jentic One can pin the agent to a single project, so it reads that project's forms, submissions, and fields and touches no other project. You decide which operations the agent may call, so an action like creating a user via POST /users stays off-limits unless you explicitly add it. Your own rules govern which operations and which stored credential the agent uses at execution time.