Avni

Avni is an open-source field-data platform for health, livelihoods, and social-sector programs, designed to support frontline workers and program managers with offline-capable mobile data collection, longitudinal beneficiary tracking, and a web console for program design and analytics. The Avni external API exposes the core domain entities — subjects, program enrolments, encounters, program encounters, and tasks — for read and write integrations, enabling third-party systems to ingest beneficiary data, sync longitudinal records, and create tasks that drive frontline workflows.

Power end-to-end data operations for your Avni API with Nexla. Our bi-directional Avni connector is purpose-built for Avni, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Avni or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Avni workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

• Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
• Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
• API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
• Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites

Avni's external API uses an OAuth 2.0 client-credentials (2-legged) flow against AWS Cognito (or Keycloak for on-premise deployments). The resulting JWT is sent to the Avni API on every request through the custom AUTH-TOKEN header (no Bearer prefix). Before creating a credential in Nexla, gather the following information from your Avni administrator or the Avni implementation team.

Identify Your Avni Deployment

Avni can be reached via the Avni-hosted SaaS environments or a self-hosted Avni server. The values you need depend on your deployment:

• Base URL — The Avni server endpoint. For Avni-hosted environments this is typically https://app.avniproject.org (production) or https://staging.avniproject.org (staging). Self-hosted deployments use the hostname configured for the Avni server.

• Access Token URL — The OAuth 2.0 token endpoint of the identity provider that issues Avni JWTs. For AWS Cognito-backed Avni deployments this is the Cognito user-pool token endpoint, in the form https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/token. For on-premise deployments backed by Keycloak, this is the Keycloak token endpoint in the form https://<keycloak-host>/auth/realms/<realm>/protocol/openid-connect/token.

• Client ID and Client Secret — The OAuth 2.0 app-client credentials configured in the identity provider for machine-to-machine access to Avni. These are issued by the Avni implementation team for self-hosted deployments, or by your Avni implementation partner for SaaS deployments.

Request API Access from Avni

The Avni public REST endpoints are intended for third-party integrations and are documented in the Avni API Guide. The internal endpoints used by the Avni mobile and web apps are not designed for integration and are not documented for external use — only the documented /api/* endpoints (subjects, enrolments, encounters, program encounters, tasks, datasets, segments, locations, notes) should be used.

1. Contact the Avni team or your implementation partner to confirm that the external API is enabled for your organization and to request an OAuth 2.0 app client for machine-to-machine integrations. Avni issues a dedicated client ID and client secret for each integration so access can be audited and rotated independently.

2. Provide the integration's purpose and the entities (subjects, enrolments, encounters, etc.) it needs to read or write so that appropriate permissions can be assigned. Avni's permission model is role-based — the user account associated with your OAuth app client must have access to the subject types, programs, and operations your integration requires.

3. Confirm with your Avni administrator which Avni server (production, staging, or self-hosted) the integration should target, and note the corresponding Base URL.

Retrieve OAuth 2.0 Credentials

Once Avni has provisioned an app client, retrieve the credential values:

1. Obtain the Client ID and Client Secret from your Avni administrator (for AWS Cognito-backed deployments) or from the Keycloak admin console (for on-premise deployments). Store both values in a secure secret manager — the Client Secret is treated as a password and should never be committed to source control.

2. Obtain the Access Token URL:

   • AWS Cognito-backed Avni: In the Cognito user pool, the token endpoint is shown under App integration > Domain as https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/token. Your Avni administrator can provide this value.

   • Keycloak-backed Avni (on-premise): The token endpoint is exposed at https://<keycloak-host>/auth/realms/<realm>/protocol/openid-connect/token. The realm name is typically avni. Your Avni administrator can provide the exact value.

3. Confirm the Base URL of the Avni server. The base URL must not include a trailing slash and must not include the /api path — Nexla appends the endpoint path automatically. For example, use https://app.avniproject.org, not https://app.avniproject.org/ or https://app.avniproject.org/api.

For complete information about the Avni external API and its authentication model, see the Avni API Guide and the Avni external API Swagger specification.

Important

The Client Secret grants programmatic access to your Avni organization's data. Store it in a secure secret manager, never commit it to source control, and rotate it immediately if you suspect it has been exposed. Coordinate rotation with your Avni administrator so the new secret can be provisioned in the identity provider.

Authenticate

Create a credential in Nexla

1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

Avni uses the OAuth 2.0 client-credentials (2-legged) flow. Nexla exchanges the Client ID and Client Secret for a JWT at the configured token URL, then sends the token to the Avni API on every request through the custom AUTH-TOKEN header.

3. Enter the OAuth 2.0 Client ID issued for your Avni integration in the Client ID field. This value is the public identifier of the app client configured in AWS Cognito or Keycloak for machine-to-machine access to Avni.

4. Enter the corresponding Client Secret in the Client Secret field. The client secret is treated as a password and is stored encrypted by Nexla.

5. Enter the OAuth 2.0 token endpoint in the Access Token URL field. This is the URL Nexla calls to exchange the client ID and client secret for a JWT.

   • AWS Cognito-backed Avni: Use the Cognito user-pool token endpoint, for example https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/token.

   • Keycloak-backed Avni (on-premise): Use the Keycloak token endpoint, for example https://<keycloak-host>/auth/realms/<realm>/protocol/openid-connect/token.

6. Enter the Avni server endpoint in the Base URL field. This is the root URL of the Avni server, without a trailing slash and without the /api path. For example, enter https://app.avniproject.org for the Avni production environment, or the hostname of your self-hosted Avni server.

   Nexla appends the endpoint path (for example, /api/subjects or /api/encounters) to the base URL automatically when calling Avni. Do not include any path segments in the Base URL field.

7. Click the Save button at the bottom of the overlay to save the configured credential. Nexla automatically performs a test call against GET /api/locations?size=1 to verify that the OAuth flow succeeds and that the resulting JWT is accepted by the Avni server. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Use as a data source

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Avni connector tile, then select the credential that will be used to connect to the Avni instance, and click Next; or, create a new Avni credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Avni endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Click on an endpoint below to see more information about it and how to configure your data source for that endpoint.

List Subjects

This endpoint returns a paginated list of Avni subjects — the top-level entity in the Avni domain model, representing the people, households, or other units that programs are run for. Use this endpoint to sync your beneficiary registry into a warehouse, build longitudinal cohorts, or feed downstream analytics.

• Enter an ISO 8601 datetime in the Last Modified Date Time field to fetch only subjects modified on or after that timestamp. Leave the field blank to fetch all subjects. For incremental syncs, use a datetime macro such as {'{now-1}'} with a Day time unit to pull subjects modified in the last 24 hours.
• Enter the page size in the Page Size field (Avni's default is 100). Smaller pages reduce per-request payload size but require more round trips.
• Enter the zero-indexed starting page in the Page Number field. Nexla advances the page automatically; in most cases this should be set to 0.

Avni list endpoints return data under $.pageOfResources[*], which is set automatically by the template. Observation dates within each subject are returned in yyyy-MM-dd format rather than ISO timestamps. For complete field reference, see the Avni API Guide.

Get Subject

This endpoint retrieves a single Avni subject by its internal ID or UUID. Use it to enrich an existing dataset of subject IDs with the latest full subject record, or to drive a chained API call from another source.

• Enter the subject's internal ID or UUID in the Id field. Subject IDs and UUIDs can be obtained from the List Subjects endpoint or from upstream Nexla data flows.

This endpoint returns a single subject object (not a paginated array). The path to data is set to the response root ($) so the subject is treated as the record.

Get Subject With All Entities

This endpoint retrieves a subject and all its related entities — enrolments, encounters, program encounters, checklists, and relationships — in a single call. Use it to hydrate a complete longitudinal record for one subject without making multiple round trips.

• Enter the subject's UUID in the Subject UUID field. The internal numeric ID is not accepted by this endpoint — only the UUID. UUIDs can be obtained from the List Subjects endpoint.

This endpoint is significantly heavier than Get Subject. Use it when you need the complete history for a small set of subjects; for bulk longitudinal extracts, the individual list endpoints (List Enrolments, List Encounters, List Program Encounters) with lastModifiedDateTime filters are more efficient.

List Enrolments

This endpoint returns a paginated list of Avni program enrolments — the registration of a subject into a longitudinal program (for example, antenatal care, child nutrition, or a livelihoods scheme). Use it to sync program participation into a warehouse or to feed downstream cohort analysis.

• Enter an ISO 8601 datetime in the Last Modified Date Time field to fetch only enrolments modified on or after that timestamp. For incremental syncs, use a datetime macro such as {'{now-1}'}.
• Enter the page size in the Page Size field (Avni's default is 100).
• Enter the zero-indexed starting page in the Page Number field — typically 0.

Each enrolment is a child of a subject. Observation dates within enrolment records are returned in yyyy-MM-dd format rather than ISO timestamps.

Get Enrolment

This endpoint retrieves a single program enrolment by its internal ID or UUID. Use it to fetch the full enrolment record — including observations recorded at enrolment and exit — for a known enrolment.

• Enter the enrolment's internal ID or UUID in the Id field. Enrolment IDs and UUIDs can be obtained from the List Enrolments endpoint.

List Encounters

This endpoint returns a paginated list of general subject encounters — visits or interactions with a subject that are not part of a program (for example, a one-off home visit or a non-programmatic health checkup). Use it to sync ad-hoc visit data into a warehouse.

• Enter an ISO 8601 datetime in the Last Modified Date Time field to fetch only encounters modified on or after that timestamp. For incremental syncs, combine this with a datetime macro such as {'{now-1}'}.
• Enter the page size in the Page Size field (Avni's default is 100).
• Enter the zero-indexed starting page in the Page Number field — typically 0.

General encounters are distinct from program encounters. To sync visits made within an enrolled program (such as antenatal-care visits), use the List Program Encounters endpoint instead.

Get Encounter

This endpoint retrieves a single general subject encounter by its internal ID or UUID. Use it to fetch the full record for one encounter, including observations and cancellation observations.

• Enter the encounter's internal ID or UUID in the Encounter ID field. Encounter IDs and UUIDs can be obtained from the List Encounters endpoint.

List Program Encounters

This endpoint returns a paginated list of program encounters — visits made within the context of a program enrolment (for example, a scheduled antenatal-care visit or a growth-monitoring check). Use it to sync longitudinal program visit data into a warehouse for cohort analysis or reporting.

• Enter an ISO 8601 datetime in the Last Modified Date Time field to fetch only program encounters modified on or after that timestamp.
• Enter the page size in the Page Size field (Avni's default is 100).
• Enter the zero-indexed starting page in the Page Number field — typically 0.

Program encounters are children of an enrolment, which is in turn a child of a subject. To reconstruct the full hierarchy downstream, join program encounters to enrolments by the enrolment UUID, and enrolments to subjects by the subject UUID.

Get Program Encounter

This endpoint retrieves a single program encounter by its internal ID or UUID. Use it to fetch the full record for one program-encounter visit.

• Enter the program encounter's internal ID or UUID in the Program Encounter ID field. IDs and UUIDs can be obtained from the List Program Encounters endpoint.

List Tasks

This endpoint returns a paginated list of Avni tasks — actionable items (call tasks or open-subject tasks) assigned to frontline workers. Use it to sync the task queue into a downstream operations dashboard or to monitor task throughput.

• Enter an ISO 8601 datetime in the Last Modified Date-Time field to fetch only tasks modified on or after that timestamp.
• Enter the page size in the Page Size field. The default page size for the tasks endpoint is 50.
• Enter the zero-based starting page in the Page Number field — typically 0.

The tasks endpoint returns data under $.content[*], which is set automatically by the template. Tasks can only be created via the external API, so this list represents tasks originally created by Nexla or another integration.

Get Task

This endpoint retrieves a single task by its ID. Use it to look up the current status of a task previously created via the Create Task destination.

• Enter the task ID in the Task ID field. Task IDs are returned by the List Tasks endpoint or by the Create Task destination response.

List Datasets

This endpoint returns a list of all available Avni datasets. Datasets are pre-defined data extracts that an Avni administrator has configured for downstream consumption. Use this endpoint as a catalog to discover available datasets and their IDs.

• No configuration is required for this endpoint beyond selecting it. All datasets accessible to your OAuth client are returned automatically.

Dataset IDs returned by this endpoint are required by the Get Dataset and List Dataset Items endpoints.

Get Dataset

This endpoint retrieves a specific dataset's metadata by its ID. Use it to inspect a dataset's definition (columns, filters, source entity) before fetching its contents.

• Enter the dataset's unique identifier in the Dataset ID field. Dataset IDs can be obtained from the List Datasets endpoint.

List Dataset Items

This endpoint returns the items (rows) contained within a specific dataset. Use it to bulk-ingest the rows of a configured Avni dataset into a warehouse or downstream analytics system.

• Enter the dataset's unique identifier in the Dataset ID field. Dataset IDs can be obtained from the List Datasets endpoint.

The template's path to data is set to $.items[*], which exposes each row of the dataset as a Nexla record.

Get Segments

This endpoint returns a list of available Avni segments — named cohorts of subjects defined by an administrator. Use it to keep downstream systems in sync with the segment catalog or to enrich subject data with cohort membership.

• No configuration is required for this endpoint beyond selecting it. All segments accessible to your OAuth client are returned automatically.

List Notes

This endpoint returns a list of available notes from Avni. Use it to sync free-text notes captured by frontline workers into a downstream review or analytics system.

• No configuration is required for this endpoint beyond selecting it. All notes accessible to your OAuth client are returned automatically.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration

Avni data sources can also be manually configured to ingest data from any valid Avni external API endpoint, including endpoints not covered by the pre-built templates, custom query parameters, or chained API calls. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

All Avni external API URLs are of the form <base_url>/api/<resource> — for example, https://app.avniproject.org/api/subjects or https://app.avniproject.org/api/programEncounters. Only the documented Avni external API endpoints (under /api/*) should be used. Set the path to data according to the endpoint: $.pageOfResources[*] for the paginated list endpoints (/api/subjects, /api/enrolments, /api/encounters, /api/programEncounters), $.content[*] for /api/tasks, $.data[*] for the datasets, segments, and notes list endpoints, $.items[*] for the dataset-items endpoint, and $ for single-resource endpoints. The AUTH-TOKEN header carrying the Avni JWT is added automatically based on your credential, so it does not need to be added manually. The lastModifiedDateTime query parameter on the list endpoints expects an ISO 8601 datetime and pairs well with a datetime macro for incremental syncs.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Avni data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination

Click the + icon on the Nexset that will be sent to the Avni destination, and select the Send to Destination option from the menu. Select the Avni connector from the list of available destination connectors, then select the credential that will be used to connect to the Avni organization, and click Next; or, create a new Avni credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Avni endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

Create or Update Subject

This endpoint creates a new subject in Avni or updates an existing subject via UUID-based idempotent upsert. Use it to register beneficiaries from upstream systems (a CRM, an external registration form, or a partner system of record) or to keep subject attributes in sync with an authoritative source.

• Each record sent to this endpoint must include the Avni fields required to identify and describe a subject — at minimum a uuid (for idempotent upsert), a subjectTypeName (the subject type, such as Individual or Household, configured in Avni), the registration date, and the address-level UUID. Required observations vary by subject type and are defined in the Avni registration form.
• The full Nexset record is sent as the JSON body of the POST /api/subjects call. Use a Nexla transform to reshape upstream attributes into the field names expected by Avni.

Avni's POST operation is idempotent — supplying the same uuid updates the existing record rather than creating a duplicate. Generate UUIDs once on the source side and persist them so subsequent syncs route to the same Avni subject. For payload reference, see the Avni API Guide.

Create or Update Enrolment

This endpoint creates a new program enrolment for a subject or updates an existing enrolment via UUID-based idempotent upsert. Use it to register subjects into a longitudinal program (for example, antenatal care or a livelihoods scheme) from an upstream system.

• Each record must include the enrolment uuid, the parent subjectUUID (the subject the enrolment belongs to), the program name, and the enrolmentDateTime. Program-specific enrolment observations should match the program's enrolment form definition in Avni.
• The full Nexset record is sent as the JSON body of the POST /api/enrolments call.

An enrolment must reference an existing subject in Avni — ensure that the upstream subject has been synced via Create or Update Subject (or already exists in Avni) before sending an enrolment with the matching subjectUUID.

Create or Update Encounter

This endpoint creates a new general subject encounter (one that is not part of a program) or updates an existing encounter via UUID-based idempotent upsert. Use it to record ad-hoc visits or non-programmatic interactions captured in an external system.

• Each record must include the encounter uuid, the parent subjectUUID, the encounterType, and the encounterDateTime. Encounter observations should align with the encounter form definition in Avni.
• The full Nexset record is sent as the JSON body of the POST /api/encounters call.

To record visits that occur within an enrolled program (such as antenatal-care visits), use the Create or Update Program Encounter endpoint instead.

Create or Update Program Encounter

This endpoint creates a new program encounter (a visit within an enrolment) or updates an existing program encounter via UUID-based idempotent upsert. Use it to push program-visit data — such as scheduled antenatal-care visits or growth-monitoring checks — from an upstream system into Avni.

• Each record must include the program-encounter uuid, the parent programEnrolmentUUID (the enrolment the visit belongs to), the encounterType, and the encounterDateTime. Visit observations should align with the program-encounter form definition in Avni.
• The full Nexset record is sent as the JSON body of the POST /api/programEncounters call.

A program encounter must reference an existing enrolment in Avni — sync upstream enrolments via Create or Update Enrolment before sending program encounters that reference them.

Create Task

This endpoint creates a task in Avni. Tasks can only be created via the external API and are surfaced to frontline workers in the Avni app — use this endpoint to drive action items from upstream systems, such as automated outreach lists, escalations, or follow-up calls.

• Each record must include the task name, the taskTypeName, and the relevant scheduling/assignment fields expected by your Avni task type. Avni supports two task types: call tasks (used for outbound calls to a subject) and openSubject tasks (used to direct a worker to open a specific subject record).
• The full Nexset record is sent as the JSON body of the POST /api/tasks call. Use a Nexla transform to shape upstream attributes into the field names expected by Avni's task schema.

Tasks are write-only via this endpoint — once created, their lifecycle (in-progress, completed, etc.) is managed inside the Avni app by frontline workers. Use the List Tasks source endpoint to monitor task status downstream.

Manual configuration

Avni destinations can also be manually configured to send data to any valid Avni external API endpoint. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

Avni's external write endpoints use POST with application/json content for idempotent create-or-update operations on subjects, enrolments, encounters, program encounters, and tasks. All URLs are of the form <base_url>/api/<resource>, and the UUID is included in the JSON body rather than the URL path. The AUTH-TOKEN header carrying the Avni JWT and the Content-Type: application/json header are added automatically. Because Avni expects one entity per request, the pre-built templates send each record in its own API call (batch.mode: false) — only enable record batching if you are calling a custom endpoint that accepts arrays of entities. Optionally enable the response webhook to capture the IDs and UUIDs Avni assigns on each call.

Important

Avni's POST endpoints are idempotent and will create or modify production data. Use a non-production Avni environment (or a dedicated test organization) when sending test payloads, and verify the assigned UUIDs in the Avni web console before activating the destination.

Save & activate

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To begin sending the Nexset data to Avni, open the destination resource menu, and select Activate.

The Nexset data will not be sent to Avni until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.