CommCare API reference

New to Corsair? See API access, authentication, and error handling.

Cases

bulkFetch

cases.bulkFetch Fetch many cases by ID in one call, optionally limited to specific fields and properties Risk: read

await corsair.commcare.api.cases.bulkFetch({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', caseIds: ['abc123', 'def456'], fields: ['case_id'] });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`caseIds`	`string[]`	Yes	Case IDs to fetch in one call; an id that is not found comes back as a stub with `error: "not found"`.
`fields`	`string[]`	No	Top-level case fields to include, e.g. `case_id`.
`fieldsProperties`	`string[]`	No	Case properties to include, e.g. `dob`.

Output

Name	Type	Required	Description
`matching_records`	`number \| null`	No	—
`missing_records`	`number \| null`	No	—
`cases`	`object[]`	Yes	—
`next`	`string \| null`	No	—
`nextCursor`	`string \| null`	No	—

cases full type

{
  case_id?: string | null,
  domain?: string | null,
  case_type?: string | null,
  case_name?: string | null,
  external_id?: string | null,
  owner_id?: string | null,
  date_opened?: string | null,
  last_modified?: string | null,
  server_last_modified?: string | null,
  closed?: boolean | null,
  date_closed?: string | null,
  properties?: Record<string, any> | null,
  indices?: Record<string, any> | null
}[]

get

cases.get Read one case with its properties and indices Risk: read

await corsair.commcare.api.cases.get({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', caseId: '8f8fd909-684f-402d-a892-f50e607fffef' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`caseId`	`string`	Yes	Case ID (UUID).

Output

Name	Type	Required	Description
`case_id`	`string \| null`	No	—
`domain`	`string \| null`	No	—
`case_type`	`string \| null`	No	—
`case_name`	`string \| null`	No	—
`external_id`	`string \| null`	No	—
`owner_id`	`string \| null`	No	—
`date_opened`	`string \| null`	No	—
`last_modified`	`string \| null`	No	—
`server_last_modified`	`string \| null`	No	—
`closed`	`boolean \| null`	No	—
`date_closed`	`string \| null`	No	—
`properties`	`Record<string, any> \| null`	No	—
`indices`	`Record<string, any> \| null`	No	—

getByExternalId

cases.getByExternalId Look up a case by the external id the application assigned it Risk: read

await corsair.commcare.api.cases.getByExternalId({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', externalId: '1' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`externalId`	`string`	Yes	External id the application assigned to the case. The lookup takes no case type; if several cases share the id, CommCare answers 400 and lists them.

Output

Name	Type	Required	Description
`case_id`	`string \| null`	No	—
`domain`	`string \| null`	No	—
`case_type`	`string \| null`	No	—
`case_name`	`string \| null`	No	—
`external_id`	`string \| null`	No	—
`owner_id`	`string \| null`	No	—
`date_opened`	`string \| null`	No	—
`last_modified`	`string \| null`	No	—
`server_last_modified`	`string \| null`	No	—
`closed`	`boolean \| null`	No	—
`date_closed`	`string \| null`	No	—
`properties`	`Record<string, any> \| null`	No	—
`indices`	`Record<string, any> \| null`	No	—

list

cases.list List cases (Case Data API v2) with cursor paging and filters for case type, owner, name, closed state and indices Risk: read

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

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`cursor`	`string`	No	`nextCursor` from the previous page; omit for the oldest page. The cursor carries the first page’s filters, so filters sent with it are ignored.
`limit`	`number`	No	Page size, up to 5000; the default is 20.
`caseType`	`string`	No	Only cases of this case type.
`ownerId`	`string`	No	Only cases owned by this user or group id.
`caseName`	`string`	No	Only cases with this name.
`closed`	`boolean`	No	true lists closed cases, false open ones.
`externalId`	`string`	No	Only the case with this external id.
`indicesParent`	`string`	No	Only child cases whose parent index points to this case id.
`indicesHost`	`string`	No	Only cases whose host index points to this case id.

Output

Name	Type	Required	Description
`matching_records`	`number \| null`	No	—
`missing_records`	`number \| null`	No	—
`cases`	`object[]`	Yes	—
`next`	`string \| null`	No	—
`nextCursor`	`string \| null`	No	—

cases full type

{
  case_id?: string | null,
  domain?: string | null,
  case_type?: string | null,
  case_name?: string | null,
  external_id?: string | null,
  owner_id?: string | null,
  date_opened?: string | null,
  last_modified?: string | null,
  server_last_modified?: string | null,
  closed?: boolean | null,
  date_closed?: string | null,
  properties?: Record<string, any> | null,
  indices?: Record<string, any> | null
}[]

Det Exports

list

detExports.list List the Data Export Tool export instances in the project Risk: read

await corsair.commcare.api.detExports.list({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`limit`	`number`	No	Page size; the default is 20.
`offset`	`number`	No	Records to skip before this page.

Output

Name	Type	Required	Description
`detExports`	`object[]`	Yes	—

detExports full type

{
  id?: string | null,
  name?: string | null,
  type?: string | null,
  export_format?: string | null
}[]

Fixtures

getItem

fixtures.getItem Read one fixture item by id Risk: read

await corsair.commcare.api.fixtures.getItem({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', itemId: '1J9NF7B4FT' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`itemId`	`string`	Yes	Fixture item ID to retrieve.

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`fixture_type`	`string \| null`	No	—
`fields`	`Record<string, any> \| null`	No	—

list

fixtures.list List lookup-table fixture items, optionally filtered by fixture type Risk: read

await corsair.commcare.api.fixtures.list({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', fixtureType: 'city' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`limit`	`number`	No	Page size; the default is 20.
`offset`	`number`	No	Records to skip before this page.
`fixtureType`	`string`	No	Only rows of the lookup table with this tag (the `tag` from lookupTables.list).

Output

Name	Type	Required	Description
`objects`	`object[]`	Yes	—
`meta`	`object \| null`	No	—
`nextPageUrl`	`string \| null`	No	—

objects full type

{
  id?: string | null,
  fixture_type?: string | null,
  fields?: Record<string, any> | null
}[]

meta full type

{
  limit?: number | null,
  next?: string | null,
  offset?: number | null,
  previous?: string | null,
  total_count?: number | null
} | null

Forms

bulkAction

forms.bulkAction Archive, unarchive, or permanently delete up to 5000 forms in one background job (delete needs the forms archived first); follow with forms.bulkActionStatus until status is complete or failed Risk: destructive · Irreversible

await corsair.commcare.api.forms.bulkAction({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', action: 'archive', formIds: ['3a1b...', '9c4d...'] });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`action`	`archive \| unarchive \| delete`	Yes	What to do to the listed forms; delete is permanent.
`formIds`	`string[]`	Yes	Up to 5000 form IDs per request; duplicate ids are collapsed.

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`action`	`string \| null`	No	—
`status`	`string \| null`	No	—
`requested_by`	`string \| null`	No	—
`requested`	`number \| null`	No	—
`processed`	`number \| null`	No	—
`succeeded`	`number \| null`	No	—
`skipped`	`Record<string, any> \| null`	No	—
`created_at`	`string \| null`	No	—
`started_at`	`string \| null`	No	—
`completed_at`	`string \| null`	No	—
`status_url`	`string \| null`	No	—
`message`	`string \| null`	No	—

bulkActionStatus

forms.bulkActionStatus Where a bulk form action stands: pending, complete, or failed, with processed and succeeded counts Risk: read

await corsair.commcare.api.forms.bulkActionStatus({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', actionId: '0f3a9c' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`actionId`	`string`	Yes	Bulk action ID from a bulk action creation.

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`action`	`string \| null`	No	—
`status`	`string \| null`	No	—
`requested_by`	`string \| null`	No	—
`requested`	`number \| null`	No	—
`processed`	`number \| null`	No	—
`succeeded`	`number \| null`	No	—
`skipped`	`Record<string, any> \| null`	No	—
`created_at`	`string \| null`	No	—
`started_at`	`string \| null`	No	—
`completed_at`	`string \| null`	No	—
`status_url`	`string \| null`	No	—
`message`	`string \| null`	No	—

get

forms.get Read one submitted form, including its XForm content and metadata Risk: read

await corsair.commcare.api.forms.get({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', formId: '66d7a362-18a2-4f45-bd84-06f19b408d64' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`formId`	`string`	Yes	Form ID (UUID) of the submitted form.

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`form`	`Record<string, any> \| null`	No	—
`metadata`	`Record<string, any> \| null`	No	—

list

forms.list List submitted forms with paging and time-window or xmlns filters Risk: read

await corsair.commcare.api.forms.list({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', limit: 100, offset: 0 });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`limit`	`number`	No	Page size, 1-1000; the default is 20.
`offset`	`number`	No	Records to skip before this page.
`indexedOnStart`	`string`	No	Only forms with data modified at or after this ISO date, e.g. `2021-01-01T06:05:42`.
`indexedOnEnd`	`string`	No	Only forms with data modified at or before this ISO date.
`xmlns`	`string`	No	Only forms submitted against this XML namespace.

Output

Name	Type	Required	Description
`objects`	`object[]`	Yes	—
`meta`	`object \| null`	No	—
`nextPageUrl`	`string \| null`	No	—

objects full type

{
  id?: string | null,
  form?: Record<string, any> | null,
  metadata?: Record<string, any> | null
}[]

meta full type

{
  limit?: number | null,
  next?: string | null,
  offset?: number | null,
  previous?: string | null,
  total_count?: number | null
} | null

Groups

create

groups.create Create a group, optionally with an initial member list Risk: write

await corsair.commcare.api.groups.create({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', name: 'Field team A' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`name`	`string`	Yes	Name of the new group.
`reporting`	`boolean`	No	Include the group in reporting.
`users`	`string[]`	No	Mobile worker IDs to put in the group.

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`name`	`string \| null`	No	—
`path`	`string[] \| null`	No	—
`reporting`	`boolean \| null`	No	—
`users`	`string[] \| null`	No	—

get

groups.get Read one group: name, reporting flag and member user ids Risk: read

await corsair.commcare.api.groups.get({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', groupId: '91da6b1c78699adfb8679b741caf9f00' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`groupId`	`string`	Yes	Group ID (UUID).

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`name`	`string \| null`	No	—
`path`	`string[] \| null`	No	—
`reporting`	`boolean \| null`	No	—
`users`	`string[] \| null`	No	—

list

groups.list List the reporting and case-sharing groups in the project with their members Risk: read

await corsair.commcare.api.groups.list({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`limit`	`number`	No	Page size; the default is 20.
`offset`	`number`	No	Records to skip before this page.

Output

Name	Type	Required	Description
`objects`	`object[]`	Yes	—
`meta`	`object \| null`	No	—
`nextPageUrl`	`string \| null`	No	—

objects full type

{
  id?: string | null,
  name?: string | null,
  path?: string[] | null,
  reporting?: boolean | null,
  users?: string[] | null
}[]

meta full type

{
  limit?: number | null,
  next?: string | null,
  offset?: number | null,
  previous?: string | null,
  total_count?: number | null
} | null

update

groups.update Rename a group, toggle reporting, or replace its member list Risk: write

await corsair.commcare.api.groups.update({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', groupId: '91da6b1c78699adfb8679b741caf9f00', reporting: true });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`groupId`	`string`	Yes	Group ID to update.
`name`	`string`	No	New name for the group.
`reporting`	`boolean`	No	Include the group in reporting.
`users`	`string[]`	No	Full replacement list of member user IDs.

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`name`	`string \| null`	No	—
`path`	`string[] \| null`	No	—
`reporting`	`boolean \| null`	No	—
`users`	`string[] \| null`	No	—

Locations

get

locations.get Read one location with its type and parent Risk: read

await corsair.commcare.api.locations.get({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', locationId: '68e65fbc2dc840ff8bf03849e57aca88' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`locationId`	`string`	Yes	Location ID to retrieve.

Output

Name	Type	Required	Description
`location_id`	`string \| null`	No	—
`name`	`string \| null`	No	—
`site_code`	`string \| null`	No	—
`location_type_code`	`string \| null`	No	—
`location_type_name`	`string \| null`	No	—
`parent_location_id`	`string \| null`	No	—
`longitude`	`string \| null`	No	—
`latitude`	`string \| null`	No	—

list

locations.list List project locations with site code, name and location type filters Risk: read

await corsair.commcare.api.locations.list({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', locationTypeCode: 'clinic' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`limit`	`number`	No	Page size; the default is 20.
`offset`	`number`	No	Records to skip before this page.
`siteCode`	`string`	No	Only the location with this site code.
`name`	`string`	No	Only locations with this name.
`locationTypeCode`	`string`	No	Only locations of this location type.

Output

Name	Type	Required	Description
`objects`	`object[]`	Yes	—
`meta`	`object \| null`	No	—
`nextPageUrl`	`string \| null`	No	—

objects full type

{
  location_id?: string | null,
  name?: string | null,
  site_code?: string | null,
  location_type_code?: string | null,
  location_type_name?: string | null,
  parent_location_id?: string | null,
  longitude?: string | null,
  latitude?: string | null
}[]

meta full type

{
  limit?: number | null,
  next?: string | null,
  offset?: number | null,
  previous?: string | null,
  total_count?: number | null
} | null

Location Types

get

locationTypes.get Read one location type by id Risk: read

await corsair.commcare.api.locationTypes.get({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', typeId: 1 });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`typeId`	`number`	Yes	Location type ID to retrieve.

Output

Name	Type	Required	Description
`id`	`number \| null`	No	—
`code`	`string \| null`	No	—
`name`	`string \| null`	No	—
`administrative`	`boolean \| null`	No	—
`domain`	`string \| null`	No	—
`parent`	`any \| null`	No	—

list

locationTypes.list List the location types defined in the project Risk: read

await corsair.commcare.api.locationTypes.list({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`limit`	`number`	No	Page size; the default is 20.
`offset`	`number`	No	Records to skip before this page.

Output

Name	Type	Required	Description
`objects`	`object[]`	Yes	—
`meta`	`object \| null`	No	—
`nextPageUrl`	`string \| null`	No	—

objects full type

{
  id?: number | null,
  code?: string | null,
  name?: string | null,
  administrative?: boolean | null,
  domain?: string | null,
  parent?: any | null
}[]

meta full type

{
  limit?: number | null,
  next?: string | null,
  offset?: number | null,
  previous?: string | null,
  total_count?: number | null
} | null

Lookup Tables

get

lookupTables.get Read one lookup table with its field definitions Risk: read

await corsair.commcare.api.lookupTables.get({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', tableId: 'bcf49791f7f04f09bd46262097e107f2' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`tableId`	`string`	Yes	Lookup table ID to retrieve.

Output

Name	Type	Required	Description
`id`	`string \| null`	No	—
`tag`	`string \| null`	No	—
`is_global`	`boolean \| null`	No	—
`fields`	`object[] \| null`	No	—
`item_attributes`	`string[] \| null`	No	—

fields full type

{
  field_name: string,
  properties?: string[] | null
}[] | null

list

lookupTables.list List the lookup tables defined in the project Risk: read

await corsair.commcare.api.lookupTables.list({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`limit`	`number`	No	Page size; the default is 20.
`offset`	`number`	No	Records to skip before this page.

Output

Name	Type	Required	Description
`objects`	`object[]`	Yes	—
`meta`	`object \| null`	No	—
`nextPageUrl`	`string \| null`	No	—

objects full type

{
  id?: string | null,
  tag?: string | null,
  is_global?: boolean | null,
  fields?: {
    field_name: string,
    properties?: string[] | null
  }[] | null,
  item_attributes?: string[] | null
}[]

meta full type

{
  limit?: number | null,
  next?: string | null,
  offset?: number | null,
  previous?: string | null,
  total_count?: number | null
} | null

Ota

restore

ota.restore Pull the OTA restore XML (user registration plus case blocks) for the API key owner in the domain; large payloads. HQ accepts the ApiKey header here and restores the account that owns the key. The password hash in the registration block is replaced with [removed] Risk: read

await corsair.commcare.api.ota.restore({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.

Output

Name	Type	Required	Description
`raw`	`string`	Yes	—

Reports

getData

reports.getData Run a configurable report and read its rows, with offset, limit (max 50) and the report filter parameters Risk: read

await corsair.commcare.api.reports.getData({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', reportId: '9aab0eeb88555a7b4568676883e7379a', offset: 0, limit: 50 });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`reportId`	`string`	Yes	Report ID from `reports.list` (the configurable report configuration id).
`offset`	`number`	No	Records to skip before this page.
`limit`	`number`	No	Page size, maximum 50.
`filters`	`Record<string, string>`	No	Report filter parameters the report defines, e.g. `state` or `gender`.

Output

Name	Type	Required	Description
`columns`	`Record<string, any>[] \| null`	No	—
`data`	`Record<string, any>[] \| null`	No	—
`next_page`	`string \| null`	No	—
`total_records`	`number \| null`	No	—

list

reports.list List the configurable reports defined in the project, with their ids Risk: read

await corsair.commcare.api.reports.list({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.

Output

Name	Type	Required	Description
`reports`	`object[]`	Yes	—

reports full type

{
  id: string,
  title?: string | null
}[]

Submissions

submit

submissions.submit Submit a complete XForm XML document to the OpenRosa receiver. Fails when HQ received the form but did not process it (nature submit_error or processing_failure); otherwise answers the message and its nature Risk: write

await corsair.commcare.api.submissions.submit({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', appId: '952a0b480c7c10dde777b2485375d2237', xml: '<xform>...</xform>' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`appId`	`string`	Yes	Application ID the form belongs to.
`xml`	`string`	Yes	The complete XForm XML document to submit, as `xml_submission_file`.

Output

Name	Type	Required	Description
`raw`	`string`	Yes	—
`message`	`string \| null`	No	—
`nature`	`string \| null`	No	OpenRosa response nature, e.g. `submit_success` or `post_processing_failure` (the form was saved but a later step failed).

Users

create

users.create Create a mobile worker account with an initial password Risk: write

await corsair.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' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`workerUsername`	`string`	Yes	Login name for the new worker, including the domain suffix, e.g. `jdoe@my-project.commcarehq.org`.
`password`	`string`	Yes	Initial password for the worker.
`firstName`	`string`	Yes	First name of the worker.
`lastName`	`string`	Yes	Last name of the worker.
`email`	`string`	No	Email address of the worker.
`phoneNumber`	`string`	No	Phone number to make the worker’s default; sent as `default_phone_number` and added to their numbers.
`userData`	`Record<string, any>`	No	Custom user data fields the application defines.

Output

Name	Type	Required	Description
`type`	`string \| null`	No	—
`id`	`string \| null`	No	—
`username`	`string \| null`	No	—
`first_name`	`string \| null`	No	—
`last_name`	`string \| null`	No	—
`email`	`string \| null`	No	—
`default_phone_number`	`string \| null`	No	—
`phone_numbers`	`string[] \| null`	No	—
`user_data`	`Record<string, any> \| null`	No	—

delete

users.delete Permanently delete a mobile worker account Risk: destructive · Irreversible

await corsair.commcare.api.users.delete({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', userId: '3c5a623af057e23a32ae4000cf291339' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`userId`	`string`	Yes	Mobile worker ID (UUID).

Output: empty object

get

users.get Read one mobile worker: username, names, email, phones and user data Risk: read

await corsair.commcare.api.users.get({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', userId: '3c5a623af057e23a32ae4000cf291339' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`userId`	`string`	Yes	Mobile worker ID (UUID).

Output

Name	Type	Required	Description
`type`	`string \| null`	No	—
`id`	`string \| null`	No	—
`username`	`string \| null`	No	—
`first_name`	`string \| null`	No	—
`last_name`	`string \| null`	No	—
`email`	`string \| null`	No	—
`default_phone_number`	`string \| null`	No	—
`phone_numbers`	`string[] \| null`	No	—
`user_data`	`Record<string, any> \| null`	No	—

list

users.list List the mobile workers in the project with paging Risk: read

await corsair.commcare.api.users.list({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', limit: 50 });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`limit`	`number`	No	Page size; the default is 20.
`offset`	`number`	No	Records to skip before this page.

Output

Name	Type	Required	Description
`objects`	`object[]`	Yes	—
`meta`	`object \| null`	No	—
`nextPageUrl`	`string \| null`	No	—

objects full type

{
  type?: string | null,
  id?: string | null,
  username?: string | null,
  first_name?: string | null,
  last_name?: string | null,
  email?: string | null,
  default_phone_number?: string | null,
  phone_numbers?: string[] | null,
  user_data?: Record<string, any> | null
}[]

meta full type

{
  limit?: number | null,
  next?: string | null,
  offset?: number | null,
  previous?: string | null,
  total_count?: number | null
} | null

sendPasswordReset

users.sendPasswordReset Email a password reset link to the mobile worker Risk: write

await corsair.commcare.api.users.sendPasswordReset({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', userId: '3c5a623af057e23a32ae4000cf291339' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`userId`	`string`	Yes	Mobile worker ID (UUID).

Output: empty object

update

users.update Change a mobile worker: names, email, phone number or custom user data Risk: write

await corsair.commcare.api.users.update({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project', userId: '3c5a623af057e23a32ae4000cf291339', phoneNumber: '+15551234567' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`userId`	`string`	Yes	Mobile worker ID (UUID).
`firstName`	`string`	No	First name of the worker.
`lastName`	`string`	No	Last name of the worker.
`email`	`string`	No	Email address of the worker.
`phoneNumber`	`string`	No	Phone number to make the worker’s default; sent as `default_phone_number` and added to their numbers.
`userData`	`Record<string, any>`	No	Custom user data. Replaces all of the worker’s existing user data, including system fields, so read the worker first and send the merged object.

Output

Name	Type	Required	Description
`type`	`string \| null`	No	—
`id`	`string \| null`	No	—
`username`	`string \| null`	No	—
`first_name`	`string \| null`	No	—
`last_name`	`string \| null`	No	—
`email`	`string \| null`	No	—
`default_phone_number`	`string \| null`	No	—
`phone_numbers`	`string[] \| null`	No	—
`user_data`	`Record<string, any> \| null`	No	—

Web Users

list

webUsers.list List the web users (dashboard accounts) in the project with their roles Risk: read

await corsair.commcare.api.webUsers.list({ username: 'jdoe@my-project.commcarehq.org', domain: 'my-project' });

Input

Name	Type	Required	Description
`username`	`string`	Yes	CommCare username the API key belongs to, e.g. `me@my-project.commcarehq.org`.
`domain`	`string`	Yes	CommCare project domain (HQ domain), e.g. `my-project`.
`limit`	`number`	No	Page size; the default is 20.
`offset`	`number`	No	Records to skip before this page.

Output

Name	Type	Required	Description
`objects`	`object[]`	Yes	—
`meta`	`object \| null`	No	—
`nextPageUrl`	`string \| null`	No	—

objects full type

{
  id?: string | null,
  email?: string | null,
  first_name?: string | null,
  last_name?: string | null,
  default_phone_number?: string | null,
  role?: string | null,
  is_admin?: boolean | null,
  permissions?: Record<string, any> | null
}[]

meta full type

{
  limit?: number | null,
  next?: string | null,
  offset?: number | null,
  previous?: string | null,
  total_count?: number | null
} | null

​Cases

​bulkFetch

​get

​getByExternalId

​list

​Det Exports

​list

​Fixtures

​getItem

​list

​Forms

​bulkAction

​bulkActionStatus

​get

​list

​Groups

​create

​get

​list

​update

​Locations

​get

​list

​Location Types

​get

​list

​Lookup Tables

​get

​list

​Ota

​restore

​Reports

​getData

​list

​Submissions

​submit

​Users

​create

​delete

​get

​list

​sendPasswordReset

​update

​Web Users

​list

Cases

bulkFetch

get

getByExternalId

list

Det Exports

list

Fixtures

getItem

list

Forms

bulkAction

bulkActionStatus

get

list

Groups

create

get

list

update

Locations

get

list

Location Types

get

list

Lookup Tables

get

list

Ota

restore

Reports

getData

list

Submissions

submit

Users

create

delete

get

list

sendPasswordReset

update

Web Users

list