CommCare plugin

• API access needs a plan. The JSON APIs require a Standard plan or above; on a free project they answer 401 “Your current subscription does not have access to this feature” (or 403). ota.restore is the exception: it works on a free project.
• Every endpoint is scoped to one project. All requests go to https://www.commcarehq.org/a/{domain}/.... There is no plugin-level domain or username option: pass both on every call.
• Two pagination styles. Most listings use limit and offset with a meta.total_count; cases.list pages oldest-to-newest by cursor: pass the nextCursor it answers as cursor until nextCursor is absent.
• Async bulk actions. forms.bulkAction accepts up to 5000 form ids for archive, unarchive or permanent delete, and answers a job id; follow with forms.bulkActionStatus until status is complete or failed. complete does not mean every form succeeded: compare succeeded with requested and read skipped. A form must be archived before it can be deleted.
• Writes. submissions.submit posts OpenRosa XForm XML to the receiver. HQ answers 201 even when it could not process the form; the call fails in that case (nature submit_error or processing_failure) and otherwise returns the message and its nature. users.create provisions a worker account with an initial password.
• Delete is permanent. users.delete removes a worker account, and forms.bulkAction with action delete permanently removes forms.
• OTA restore auth. ota.restore pulls the full case-restore XML. The docs show worker Basic credentials, but HQ also accepts the ApiKey header and restores the account that owns the key, so a web user’s key returns that user’s restore, not a mobile worker’s. HQ puts the owner’s password hash in the restore’s registration block; the plugin replaces it with [removed] before returning the XML.

• 32 typed API operations

​

Setup

npm install corsair @corsair-dev/commcare better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/commcare better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/commcare better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/commcare better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { commcare } from '@corsair-dev/commcare';

export const corsair = createCorsair({
	plugins: [
		commcare(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

commcare()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'commcare',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.commcare.api.cases.list({
	username: 'jdoe@my-project.commcarehq.org',
	domain: 'my-project',
	caseType: 'patient',
	closed: false,
});

const tenant = corsair.withTenant('acme');
await tenant.commcare.api.users.create({
	username: 'jdoe@my-project.commcarehq.org',
	domain: 'my-project',
	workerUsername: 'new.worker@my-project.commcarehq.org',
	password: 'change-me-1',
	firstName: 'Jordan',
	lastName: 'Lee',
});

​

What’s next