> ## 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.

# Splitwise API reference

> API reference for the Splitwise plugin in Corsair: every `splitwise.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).

## Categories

### list

`categories.list`

List expense categories with their subcategories; an expense must use a subcategory

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.categories.list({});
```

**Input:** *empty object*

An expense must reference a subcategory. A parent category ID is rejected.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `categories` | `object[]` | Yes | — |

> [accordion] categories full type
>
> ```ts theme={null}
> {
>   id: number,
>   name: string,
>   icon?: string | null,
>   icon_types?: Record<string, Record<string, string>> | null,
>   subcategories: {
>     id: number,
>     name: string,
>     icon?: string | null,
>     icon_types?: Record<string, Record<string, string>> | null
>   }[]
> }[]
> ```

***

## Comments

### create

`comments.create`

Post a comment on an expense

**Risk:** `destructive`

```ts theme={null}
await corsair.splitwise.api.comments.create({ expense_id: 51023, content: 'Does this include the delivery fee?' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `expense_id` | `number` | Yes | — |
| `content` | `string` | Yes | Comment body |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `comment` | `object` | Yes | — |

> [accordion] comment full type
>
> ```ts theme={null}
> {
>   id: number,
>   content: string,
>   comment_type?: string | null,
>   relation_type?: string | null,
>   relation_id?: number | null,
>   created_at?: string | null,
>   deleted_at?: string | null,
>   user?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null
>   } | null
> }
> ```

***

### delete

`comments.delete`

Delete a comment; this cannot be undone

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.splitwise.api.comments.delete({ comment_id: 79800950 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `comment_id` | `number` | Yes | — |

A deleted comment cannot be restored.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `comment` | `object` | Yes | — |

> [accordion] comment full type
>
> ```ts theme={null}
> {
>   id: number,
>   content: string,
>   comment_type?: string | null,
>   relation_type?: string | null,
>   relation_id?: number | null,
>   created_at?: string | null,
>   deleted_at?: string | null,
>   user?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null
>   } | null
> }
> ```

***

### list

`comments.list`

List the comments on an expense

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.comments.list({ expense_id: 51023 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `expense_id` | `number` | Yes | Expense whose comments to read |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `comments` | `object[]` | Yes | — |

> [accordion] comments full type
>
> ```ts theme={null}
> {
>   id: number,
>   content: string,
>   comment_type?: string | null,
>   relation_type?: string | null,
>   relation_id?: number | null,
>   created_at?: string | null,
>   deleted_at?: string | null,
>   user?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null
>   } | null
> }[]
> ```

***

## Currencies

### list

`currencies.list`

List the currency codes Splitwise accepts

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.currencies.list({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `currencies` | `object[]` | Yes | — |

> [accordion] currencies full type
>
> ```ts theme={null}
> {
>   currency_code: string,
>   unit: string
> }[]
> ```

***

## Expenses

### create

`expenses.create`

Record an expense, split either equally across a group or by an explicit paid and owed share per person

**Risk:** `destructive`

```ts theme={null}
await corsair.splitwise.api.expenses.create({ description: 'Internet', cost: 60, group_id: 321, split_equally: true });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `description` | `string` | Yes | A short description of the expense |
| `cost` | `number` | Yes | Total cost of the expense, e.g. 25.5 |
| `details` | `string` | No | Free-text notes |
| `date` | `string` | No | ISO 8601 date and time the expense took place, e.g. "2026-05-02T13:00:00Z" |
| `currency_code` | `string` | No | Currency code from `currencies.list`; defaults to the group currency |
| `category_id` | `number` | No | A subcategory ID from `categories.list`; a parent category is rejected |
| `repeat_interval` | `never \| weekly \| fortnightly \| monthly \| yearly` | No | — |
| `split_equally` | `true` | No | Split equally between the group; requires `group_id` and no `users` |
| `group_id` | `number` | No | Group to put the expense in, or 0 for an expense outside a group |
| `users` | `object[]` | No | One entry per person, each with `paid_share` and `owed_share` |

Pass either `split_equally: true` with a `group_id`, or a `users` list whose paid and owed amounts add up to `cost`.

> [accordion] users full type
>
> ```ts theme={null}
> {
>   user_id?: number,
>   first_name?: string,
>   last_name?: string,
>   email?: string,
>   paid_share: number,
>   owed_share: number
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `expenses` | `object[]` | Yes | — |
| `errors` | `Record<string, string[]> \| null` | No | — |

> [accordion] expenses full type
>
> ```ts theme={null}
> {
>   id: number,
>   group_id?: number | null,
>   friendship_id?: number | null,
>   expense_bundle_id?: number | null,
>   description: string,
>   details?: string | null,
>   cost: string,
>   currency_code: string,
>   date?: string | null,
>   created_at?: string | null,
>   created_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   updated_at?: string | null,
>   updated_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   deleted_at?: string | null,
>   deleted_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   category?: {
>     id: number,
>     name: string
>   } | null,
>   receipt?: {
>     large?: string | null,
>     original?: string | null
>   } | null,
>   repeats?: boolean | null,
>   repeat_interval?: string | null,
>   email_reminder?: boolean | null,
>   email_reminder_in_advance?: number | null,
>   next_repeat?: string | null,
>   comments_count?: number | null,
>   payment?: boolean | null,
>   transaction_confirmed?: boolean | null,
>   repayments?: {
>     from: number,
>     to: number,
>     amount: string
>   }[] | null,
>   users?: {
>     user?: {
>       id: number,
>       first_name?: string | null,
>       last_name?: string | null,
>       picture?: {
>         small?: string | null,
>         medium?: string | null,
>         large?: string | null
>       } | null
>     } | null,
>     user_id: number,
>     paid_share: string,
>     owed_share: string,
>     net_balance: string
>   }[] | null,
>   comments?: {
>     id: number,
>     content: string,
>     comment_type?: string | null,
>     relation_type?: string | null,
>     relation_id?: number | null,
>     created_at?: string | null,
>     deleted_at?: string | null,
>     user?: {
>       id: number,
>       first_name?: string | null,
>       last_name?: string | null,
>       picture?: {
>         small?: string | null,
>         medium?: string | null,
>         large?: string | null
>       } | null
>     } | null
>   }[] | null
> }[]
> ```

***

### delete

`expenses.delete`

Delete an expense; it can be restored with `expenses.undelete`

**Risk:** `destructive`

```ts theme={null}
await corsair.splitwise.api.expenses.delete({ expense_id: 51023 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `expense_id` | `number` | Yes | Splitwise expense ID |

Soft delete: the expense can be restored with `expenses.undelete`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `errors` | `Record<string, string[]> \| string[] \| null` | No | — |

***

### get

`expenses.get`

Get one expense with its shares, repayments and comments

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.expenses.get({ expense_id: 51023 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `expense_id` | `number` | Yes | Splitwise expense ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `expense` | `object` | Yes | — |

> [accordion] expense full type
>
> ```ts theme={null}
> {
>   id: number,
>   group_id?: number | null,
>   friendship_id?: number | null,
>   expense_bundle_id?: number | null,
>   description: string,
>   details?: string | null,
>   cost: string,
>   currency_code: string,
>   date?: string | null,
>   created_at?: string | null,
>   created_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   updated_at?: string | null,
>   updated_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   deleted_at?: string | null,
>   deleted_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   category?: {
>     id: number,
>     name: string
>   } | null,
>   receipt?: {
>     large?: string | null,
>     original?: string | null
>   } | null,
>   repeats?: boolean | null,
>   repeat_interval?: string | null,
>   email_reminder?: boolean | null,
>   email_reminder_in_advance?: number | null,
>   next_repeat?: string | null,
>   comments_count?: number | null,
>   payment?: boolean | null,
>   transaction_confirmed?: boolean | null,
>   repayments?: {
>     from: number,
>     to: number,
>     amount: string
>   }[] | null,
>   users?: {
>     user?: {
>       id: number,
>       first_name?: string | null,
>       last_name?: string | null,
>       picture?: {
>         small?: string | null,
>         medium?: string | null,
>         large?: string | null
>       } | null
>     } | null,
>     user_id: number,
>     paid_share: string,
>     owed_share: string,
>     net_balance: string
>   }[] | null,
>   comments?: {
>     id: number,
>     content: string,
>     comment_type?: string | null,
>     relation_type?: string | null,
>     relation_id?: number | null,
>     created_at?: string | null,
>     deleted_at?: string | null,
>     user?: {
>       id: number,
>       first_name?: string | null,
>       last_name?: string | null,
>       picture?: {
>         small?: string | null,
>         medium?: string | null,
>         large?: string | null
>       } | null
>     } | null
>   }[] | null
> }
> ```

***

### list

`expenses.list`

List the current user expenses, filtered by group, friend or date, with limit and offset paging

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.expenses.list({ group_id: 321, limit: 50 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `group_id` | `number` | No | Only expenses in this group; `friend_id` is then ignored |
| `friend_id` | `number` | No | Only expenses between the current user and this user |
| `dated_after` | `string` | No | — |
| `dated_before` | `string` | No | — |
| `updated_after` | `string` | No | — |
| `updated_before` | `string` | No | — |
| `limit` | `number` | No | Default 20 |
| `offset` | `number` | No | Default 0 |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `expenses` | `object[]` | Yes | — |

> [accordion] expenses full type
>
> ```ts theme={null}
> {
>   id: number,
>   group_id?: number | null,
>   friendship_id?: number | null,
>   expense_bundle_id?: number | null,
>   description: string,
>   details?: string | null,
>   cost: string,
>   currency_code: string,
>   date?: string | null,
>   created_at?: string | null,
>   created_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   updated_at?: string | null,
>   updated_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   deleted_at?: string | null,
>   deleted_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   category?: {
>     id: number,
>     name: string
>   } | null,
>   receipt?: {
>     large?: string | null,
>     original?: string | null
>   } | null,
>   repeats?: boolean | null,
>   repeat_interval?: string | null,
>   email_reminder?: boolean | null,
>   email_reminder_in_advance?: number | null,
>   next_repeat?: string | null,
>   comments_count?: number | null,
>   payment?: boolean | null,
>   transaction_confirmed?: boolean | null,
>   repayments?: {
>     from: number,
>     to: number,
>     amount: string
>   }[] | null,
>   users?: {
>     user?: {
>       id: number,
>       first_name?: string | null,
>       last_name?: string | null,
>       picture?: {
>         small?: string | null,
>         medium?: string | null,
>         large?: string | null
>       } | null
>     } | null,
>     user_id: number,
>     paid_share: string,
>     owed_share: string,
>     net_balance: string
>   }[] | null,
>   comments?: {
>     id: number,
>     content: string,
>     comment_type?: string | null,
>     relation_type?: string | null,
>     relation_id?: number | null,
>     created_at?: string | null,
>     deleted_at?: string | null,
>     user?: {
>       id: number,
>       first_name?: string | null,
>       last_name?: string | null,
>       picture?: {
>         small?: string | null,
>         medium?: string | null,
>         large?: string | null
>       } | null
>     } | null
>   }[] | null
> }[]
> ```

***

### undelete

`expenses.undelete`

Restore a deleted expense

**Risk:** `write`

```ts theme={null}
await corsair.splitwise.api.expenses.undelete({ expense_id: 51023 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `expense_id` | `number` | Yes | Splitwise expense ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `errors` | `Record<string, string[]> \| string[] \| null` | No | — |

***

### update

`expenses.update`

Change an expense; passing any share replaces every share on it

**Risk:** `destructive`

```ts theme={null}
await corsair.splitwise.api.expenses.update({ expense_id: 51023, description: 'Brunch (updated)' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `description` | `string` | No | A short description of the expense |
| `cost` | `number` | No | Total cost of the expense, e.g. 25.5 |
| `details` | `string \| null` | No | Free-text notes; null clears them |
| `date` | `string` | No | ISO 8601 date and time the expense took place, e.g. "2026-05-02T13:00:00Z" |
| `currency_code` | `string` | No | Currency code from `currencies.list`; defaults to the group currency |
| `category_id` | `number` | No | A subcategory ID from `categories.list`; a parent category is rejected |
| `repeat_interval` | `never \| weekly \| fortnightly \| monthly \| yearly` | No | — |
| `expense_id` | `number` | Yes | ID of the expense to update |
| `group_id` | `number` | No | — |
| `users` | `object[]` | No | Replaces every share on the expense when supplied |

Passing `users` replaces every share, so `cost` is required with it. Omitted fields stay as they were.

> [accordion] users full type
>
> ```ts theme={null}
> {
>   user_id?: number,
>   first_name?: string,
>   last_name?: string,
>   email?: string,
>   paid_share: number,
>   owed_share: number
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `expenses` | `object[]` | Yes | — |
| `errors` | `Record<string, string[]> \| null` | No | — |

> [accordion] expenses full type
>
> ```ts theme={null}
> {
>   id: number,
>   group_id?: number | null,
>   friendship_id?: number | null,
>   expense_bundle_id?: number | null,
>   description: string,
>   details?: string | null,
>   cost: string,
>   currency_code: string,
>   date?: string | null,
>   created_at?: string | null,
>   created_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   updated_at?: string | null,
>   updated_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   deleted_at?: string | null,
>   deleted_by?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null
>   } | null,
>   category?: {
>     id: number,
>     name: string
>   } | null,
>   receipt?: {
>     large?: string | null,
>     original?: string | null
>   } | null,
>   repeats?: boolean | null,
>   repeat_interval?: string | null,
>   email_reminder?: boolean | null,
>   email_reminder_in_advance?: number | null,
>   next_repeat?: string | null,
>   comments_count?: number | null,
>   payment?: boolean | null,
>   transaction_confirmed?: boolean | null,
>   repayments?: {
>     from: number,
>     to: number,
>     amount: string
>   }[] | null,
>   users?: {
>     user?: {
>       id: number,
>       first_name?: string | null,
>       last_name?: string | null,
>       picture?: {
>         small?: string | null,
>         medium?: string | null,
>         large?: string | null
>       } | null
>     } | null,
>     user_id: number,
>     paid_share: string,
>     owed_share: string,
>     net_balance: string
>   }[] | null,
>   comments?: {
>     id: number,
>     content: string,
>     comment_type?: string | null,
>     relation_type?: string | null,
>     relation_id?: number | null,
>     created_at?: string | null,
>     deleted_at?: string | null,
>     user?: {
>       id: number,
>       first_name?: string | null,
>       last_name?: string | null,
>       picture?: {
>         small?: string | null,
>         medium?: string | null,
>         large?: string | null
>       } | null
>     } | null
>   }[] | null
> }[]
> ```

***

## Friends

### add

`friends.add`

Add a friend by email; a first name is needed when the person has no Splitwise account yet

**Risk:** `destructive`

```ts theme={null}
await corsair.splitwise.api.friends.add({ user_email: 'grace@example.com', user_first_name: 'Grace' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `user_email` | `string` | Yes | The friend's email address |
| `user_first_name` | `string` | No | Required only when the other person has no Splitwise account |
| `user_last_name` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `friend` | `object` | Yes | — |

> [accordion] friend full type
>
> ```ts theme={null}
> {
>   id: number,
>   first_name?: string | null,
>   last_name?: string | null,
>   email?: string | null,
>   registration_status?: string | null,
>   picture?: {
>     small?: string | null,
>     medium?: string | null,
>     large?: string | null
>   } | null,
>   custom_picture?: boolean | null,
>   groups?: {
>     group_id: number,
>     balance?: {
>       currency_code: string,
>       amount: string
>     }[] | null
>   }[] | null,
>   balance?: {
>     currency_code: string,
>     amount: string
>   }[] | null,
>   updated_at?: string | null
> }
> ```

***

### addMany

`friends.addMany`

Add several friends in one call, returning each result alongside any errors

**Risk:** `destructive`

```ts theme={null}
await corsair.splitwise.api.friends.addMany({ users: [{ email: 'grace@example.com', first_name: 'Grace' }, { email: 'alan@example.com' }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `users` | `object[]` | Yes | Friends to add in one call |

> [accordion] users full type
>
> ```ts theme={null}
> {
>   email: string,
>   first_name?: string,
>   last_name?: string
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `users` | `object[]` | Yes | — |
| `errors` | `Record<string, string[]> \| null` | No | — |

> [accordion] users full type
>
> ```ts theme={null}
> {
>   id: number,
>   first_name?: string | null,
>   last_name?: string | null,
>   email?: string | null,
>   registration_status?: string | null,
>   picture?: {
>     small?: string | null,
>     medium?: string | null,
>     large?: string | null
>   } | null,
>   custom_picture?: boolean | null,
>   groups?: {
>     group_id: number,
>     balance?: {
>       currency_code: string,
>       amount: string
>     }[] | null
>   }[] | null,
>   balance?: {
>     currency_code: string,
>     amount: string
>   }[] | null,
>   updated_at?: string | null
> }[]
> ```

***

### delete

`friends.delete`

Break off the friendship; Splitwise keeps the expenses but the friend is removed from the list and there is no undelete call

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.splitwise.api.friends.delete({ friend_id: 491923 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `friend_id` | `number` | Yes | The friend's user ID |

There is no undelete call for a friendship.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `errors` | `Record<string, string[]> \| string[] \| null` | No | — |

***

### get

`friends.get`

Get one friend with their balances and shared groups

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.friends.get({ friend_id: 491923 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `friend_id` | `number` | Yes | The friend's user ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `friend` | `object` | Yes | — |

> [accordion] friend full type
>
> ```ts theme={null}
> {
>   id: number,
>   first_name?: string | null,
>   last_name?: string | null,
>   email?: string | null,
>   registration_status?: string | null,
>   picture?: {
>     small?: string | null,
>     medium?: string | null,
>     large?: string | null
>   } | null,
>   custom_picture?: boolean | null,
>   groups?: {
>     group_id: number,
>     balance?: {
>       currency_code: string,
>       amount: string
>     }[] | null
>   }[] | null,
>   balance?: {
>     currency_code: string,
>     amount: string
>   }[] | null,
>   updated_at?: string | null
> }
> ```

***

### list

`friends.list`

List the current user friends with the balance owed either way

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.friends.list({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `friends` | `object[]` | Yes | — |

> [accordion] friends full type
>
> ```ts theme={null}
> {
>   id: number,
>   first_name?: string | null,
>   last_name?: string | null,
>   email?: string | null,
>   registration_status?: string | null,
>   picture?: {
>     small?: string | null,
>     medium?: string | null,
>     large?: string | null
>   } | null,
>   custom_picture?: boolean | null,
>   groups?: {
>     group_id: number,
>     balance?: {
>       currency_code: string,
>       amount: string
>     }[] | null
>   }[] | null,
>   balance?: {
>     currency_code: string,
>     amount: string
>   }[] | null,
>   updated_at?: string | null
> }[]
> ```

***

## Groups

### addUser

`groups.addUser`

Add a Splitwise user, or a new person by name and email, to a group

**Risk:** `destructive`

```ts theme={null}
await corsair.splitwise.api.groups.addUser({ group_id: 321, user_id: 491923 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `group_id` | `number` | Yes | — |
| `user_id` | `number` | No | — |
| `first_name` | `string` | No | — |
| `last_name` | `string` | No | — |
| `email` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `user` | `object \| null` | No | — |
| `errors` | `Record<string, string[]> \| null` | No | — |

> [accordion] user full type
>
> ```ts theme={null}
> {
>   id: number,
>   first_name?: string | null,
>   last_name?: string | null,
>   email?: string | null,
>   registration_status?: string | null,
>   picture?: {
>     small?: string | null,
>     medium?: string | null,
>     large?: string | null
>   } | null,
>   custom_picture?: boolean | null
> } | null
> ```

***

### create

`groups.create`

Create a group and add members by user ID or by name and email; the current user is added automatically

**Risk:** `destructive`

```ts theme={null}
await corsair.splitwise.api.groups.create({ name: 'Housemates 2026', group_type: 'home', users: [{ first_name: 'Grace', last_name: 'Hopper', email: 'grace@example.com' }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Name of the group |
| `group_type` | `home \| trip \| couple \| other \| apartment \| house` | No | Splitwise recommends `home` in place of `house` or `apartment` |
| `simplify_by_default` | `boolean` | No | Turn on simplify debts |
| `users` | `object[]` | No | Members to add besides the current user, who is added automatically |

Members are sent as `users__<index>__<property>` keys. A member needs either `user_id` or `email`; add `first_name` and `last_name` for someone without an account.

> [accordion] users full type
>
> ```ts theme={null}
> {
>   user_id?: number,
>   first_name?: string,
>   last_name?: string,
>   email?: string
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `group` | `object` | Yes | — |

> [accordion] group full type
>
> ```ts theme={null}
> {
>   id: number,
>   name: string,
>   group_type?: string | null,
>   updated_at?: string | null,
>   simplify_by_default?: boolean | null,
>   members?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null,
>     balance?: {
>       currency_code: string,
>       amount: string
>     }[] | null
>   }[] | null,
>   original_debts?: {
>     from: number,
>     to: number,
>     amount: string,
>     currency_code: string
>   }[] | null,
>   simplified_debts?: {
>     from: number,
>     to: number,
>     amount: string,
>     currency_code: string
>   }[] | null,
>   avatar?: {
>     original?: string | null,
>     xxlarge?: string | null,
>     xlarge?: string | null,
>     large?: string | null,
>     medium?: string | null,
>     small?: string | null
>   } | null,
>   custom_avatar?: boolean | null,
>   cover_photo?: {
>     original?: string | null,
>     xxlarge?: string | null,
>     xlarge?: string | null,
>     large?: string | null,
>     medium?: string | null,
>     small?: string | null
>   } | null
> }
> ```

***

### delete

`groups.delete`

Delete a group and every expense in it; the group can be restored with `groups.undelete`

**Risk:** `destructive`

```ts theme={null}
await corsair.splitwise.api.groups.delete({ group_id: 321 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `group_id` | `number` | Yes | Splitwise group ID |

Deletes the group and every expense in it. The group can be restored with `groups.undelete`.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `errors` | `Record<string, string[]> \| string[] \| null` | No | — |

***

### get

`groups.get`

Get one group with its members, balances and debts

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.groups.get({ group_id: 321 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `group_id` | `number` | Yes | Splitwise group ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `group` | `object` | Yes | — |

> [accordion] group full type
>
> ```ts theme={null}
> {
>   id: number,
>   name: string,
>   group_type?: string | null,
>   updated_at?: string | null,
>   simplify_by_default?: boolean | null,
>   members?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null,
>     balance?: {
>       currency_code: string,
>       amount: string
>     }[] | null
>   }[] | null,
>   original_debts?: {
>     from: number,
>     to: number,
>     amount: string,
>     currency_code: string
>   }[] | null,
>   simplified_debts?: {
>     from: number,
>     to: number,
>     amount: string,
>     currency_code: string
>   }[] | null,
>   avatar?: {
>     original?: string | null,
>     xxlarge?: string | null,
>     xlarge?: string | null,
>     large?: string | null,
>     medium?: string | null,
>     small?: string | null
>   } | null,
>   custom_avatar?: boolean | null,
>   cover_photo?: {
>     original?: string | null,
>     xxlarge?: string | null,
>     xlarge?: string | null,
>     large?: string | null,
>     medium?: string | null,
>     small?: string | null
>   } | null
> }
> ```

***

### list

`groups.list`

List the current user groups with their members, balances and simplified debts; expenses outside a group appear as group 0

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.groups.list({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `groups` | `object[]` | Yes | — |

> [accordion] groups full type
>
> ```ts theme={null}
> {
>   id: number,
>   name: string,
>   group_type?: string | null,
>   updated_at?: string | null,
>   simplify_by_default?: boolean | null,
>   members?: {
>     id: number,
>     first_name?: string | null,
>     last_name?: string | null,
>     email?: string | null,
>     registration_status?: string | null,
>     picture?: {
>       small?: string | null,
>       medium?: string | null,
>       large?: string | null
>     } | null,
>     custom_picture?: boolean | null,
>     balance?: {
>       currency_code: string,
>       amount: string
>     }[] | null
>   }[] | null,
>   original_debts?: {
>     from: number,
>     to: number,
>     amount: string,
>     currency_code: string
>   }[] | null,
>   simplified_debts?: {
>     from: number,
>     to: number,
>     amount: string,
>     currency_code: string
>   }[] | null,
>   avatar?: {
>     original?: string | null,
>     xxlarge?: string | null,
>     xlarge?: string | null,
>     large?: string | null,
>     medium?: string | null,
>     small?: string | null
>   } | null,
>   custom_avatar?: boolean | null,
>   cover_photo?: {
>     original?: string | null,
>     xxlarge?: string | null,
>     xlarge?: string | null,
>     large?: string | null,
>     medium?: string | null,
>     small?: string | null
>   } | null
> }[]
> ```

***

### removeUser

`groups.removeUser`

Remove a user from a group; Splitwise refuses while that user has a non-zero balance

**Risk:** `write`

```ts theme={null}
await corsair.splitwise.api.groups.removeUser({ group_id: 321, user_id: 491923 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `group_id` | `number` | Yes | — |
| `user_id` | `number` | Yes | — |

Splitwise refuses while the user has a non-zero balance.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `errors` | `Record<string, string[]> \| string[] \| null` | No | — |

***

### undelete

`groups.undelete`

Restore a deleted group

**Risk:** `write`

```ts theme={null}
await corsair.splitwise.api.groups.undelete({ group_id: 321 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `group_id` | `number` | Yes | Splitwise group ID |

This route reports `errors` as an array of strings rather than the map every other write uses.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `boolean` | Yes | — |
| `errors` | `string[] \| null` | No | — |

***

## Notifications

### list

`notifications.list`

List recent activity on the account, newest first, optionally after a given time

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.notifications.list({ limit: 20 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `updated_after` | `string` | No | Only notifications created after this time |
| `limit` | `number` | No | Maximum to return; omit for the provider maximum |

Omit `limit` to get the provider maximum; Splitwise imposes its own cap on very old `updated_after` values.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `notifications` | `object[]` | Yes | — |

> [accordion] notifications full type
>
> ```ts theme={null}
> {
>   id: number,
>   type: number,
>   created_at?: string | null,
>   created_by?: number | null,
>   source?: {
>     type?: string | null,
>     id?: number | null,
>     url?: string | null
>   } | null,
>   image_url?: string | null,
>   image_shape?: string | null,
>   content?: string | null
> }[]
> ```

***

## Users

### get

`users.get`

Get another user by ID; Splitwise only answers for people you share a group or expense with

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.users.get({ user_id: 491923 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `user_id` | `number` | Yes | Splitwise user ID, from `users.current` or a group member |

Splitwise only answers for people you share a group or an expense with; anyone else is a 403.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `user` | `object` | Yes | — |

> [accordion] user full type
>
> ```ts theme={null}
> {
>   id: number,
>   first_name?: string | null,
>   last_name?: string | null,
>   email?: string | null,
>   registration_status?: string | null,
>   picture?: {
>     small?: string | null,
>     medium?: string | null,
>     large?: string | null
>   } | null,
>   custom_picture?: boolean | null
> }
> ```

***

### getCurrentUser

`users.getCurrentUser`

Get the user the key belongs to, with its notification settings and unread count

**Risk:** `read`

```ts theme={null}
await corsair.splitwise.api.users.getCurrentUser({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `user` | `object` | Yes | — |

> [accordion] user full type
>
> ```ts theme={null}
> {
>   id: number,
>   first_name?: string | null,
>   last_name?: string | null,
>   email?: string | null,
>   registration_status?: string | null,
>   picture?: {
>     small?: string | null,
>     medium?: string | null,
>     large?: string | null
>   } | null,
>   custom_picture?: boolean | null,
>   notifications_read?: string | null,
>   notifications_count?: number | null,
>   notifications?: Record<string, boolean> | null,
>   default_currency?: string | null,
>   locale?: string | null
> }
> ```

***

### update

`users.update`

Change a user's name, email, password, locale or default currency

**Risk:** `write`

```ts theme={null}
await corsair.splitwise.api.users.update({ user_id: 491923, default_currency: 'EUR' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `user_id` | `number` | Yes | ID of the user to update |
| `first_name` | `string` | No | — |
| `last_name` | `string` | No | — |
| `email` | `string` | No | — |
| `password` | `string` | No | — |
| `locale` | `string` | No | ISO 639-1 two-letter locale code, e.g. "en" |
| `default_currency` | `string` | No | Currency code from `currencies.list`, e.g. "USD" |

The ID travels in the path, so it cannot also be changed through the body.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `user` | `object` | Yes | — |

> [accordion] user full type
>
> ```ts theme={null}
> {
>   id: number,
>   first_name?: string | null,
>   last_name?: string | null,
>   email?: string | null,
>   registration_status?: string | null,
>   picture?: {
>     small?: string | null,
>     medium?: string | null,
>     large?: string | null
>   } | null,
>   custom_picture?: boolean | null
> }
> ```

***


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