> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CommCare API reference

> API reference for the CommCare plugin in Corsair: every `commcare.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Cases

### bulkFetch

`cases.bulkFetch`

Fetch many cases by ID in one call, optionally limited to specific fields and properties

**Risk:** `read`

```ts theme={null}
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 | — |

> [accordion] cases full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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 | — |

> [accordion] cases full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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 | — |

> [accordion] detExports full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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`

```ts theme={null}
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 | — |

> [accordion] objects full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   fixture_type?: string | null,
>   fields?: Record<string, any> | null
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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**

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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 | — |

> [accordion] objects full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   form?: Record<string, any> | null,
>   metadata?: Record<string, any> | null
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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 | — |

> [accordion] objects full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null,
>   path?: string[] | null,
>   reporting?: boolean | null,
>   users?: string[] | null
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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 | — |

> [accordion] objects full type
>
> ```ts theme={null}
> {
>   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
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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`

```ts theme={null}
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 | — |

> [accordion] objects full type
>
> ```ts theme={null}
> {
>   id?: number | null,
>   code?: string | null,
>   name?: string | null,
>   administrative?: boolean | null,
>   domain?: string | null,
>   parent?: any | null
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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 | — |

> [accordion] fields full type
>
> ```ts theme={null}
> {
>   field_name: string,
>   properties?: string[] | null
> }[] | null
> ```

***

### list

`lookupTables.list`

List the lookup tables defined in the project

**Risk:** `read`

```ts theme={null}
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 | — |

> [accordion] objects full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   tag?: string | null,
>   is_global?: boolean | null,
>   fields?: {
>     field_name: string,
>     properties?: string[] | null
>   }[] | null,
>   item_attributes?: string[] | null
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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 | — |

> [accordion] reports full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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`

```ts theme={null}
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**

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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 | — |

> [accordion] objects full type
>
> ```ts theme={null}
> {
>   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
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   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`

```ts theme={null}
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`

```ts theme={null}
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`

```ts theme={null}
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 | — |

> [accordion] objects full type
>
> ```ts theme={null}
> {
>   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
> }[]
> ```

> [accordion] meta full type
>
> ```ts theme={null}
> {
>   limit?: number | null,
>   next?: string | null,
>   offset?: number | null,
>   previous?: string | null,
>   total_count?: number | null
> } | null
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.