Splitwise

Splitwise Groups API

A Group represents a collection of users who share expenses together. For example, some users use a Group to aggregate expenses related to a home. Others use it to represent a trip. Expenses assigned to a group are split among the users of that group. Importantly, two users in a Group can also have expenses with one another outside of the Group.

GitHub OpenAPI

Operations 7

GET /get_groups List the current user's groups #
GET /get_group/{id} Get information about a group #
POST /create_group Create a group #
POST /delete_group/{id} Delete a group #
POST /undelete_group/{id} Restore a group #
POST /add_user_to_group Add a user to a group #
POST /remove_user_from_group Remove a user from a group #

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/splitwise/refs/heads/main/openapi/splitwise-groups-api-openapi.yml

Other Resources

🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/splitwise/refs/heads/main/conventions/splitwise-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/splitwise/refs/heads/main/errors/splitwise-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/splitwise/refs/heads/main/data-model/splitwise-data-model.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/splitwise-groups-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

splitwise-groups-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  version: 3.0.0
  title: Splitwise Groups API
  x-logo:
    url: https://www.splitwise.com/assets/press/logos/sw.svg
    altText: Splitwise logo and name
  description: '# Introduction

    Hey there!'
servers:
- url: https://secure.splitwise.com/api/v3.0
  variables: {}
security:
- OAuth: []
- ApiKeyAuth: []
tags:
- name: Groups
  x-displayName: Groups
  description: A Group represents a collection of users who share expenses together. For example, some users use a Group to aggregate expenses related to a home. Others use it to represent a trip. Expenses assigned to a group are split among the users of that group. Importantly, two users in a Group can also have expenses with one another outside of the Group.
paths:
  /get_groups:
    get:
      tags:
      - Groups
      summary: List the current user's groups
      description: '**Note**: Expenses that are not associated with a group are listed in a group with ID 0.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      $ref: '#/components/schemas/group'
        '401':
          $ref: '#/components/responses/unauthorized'
      operationId: getGetGroups
      x-operation-id-source: derived
  /get_group/{id}:
    parameters:
    - in: path
      name: id
      schema:
        type: integer
      required: true
    get:
      tags:
      - Groups
      summary: Get information about a group
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  group:
                    $ref: '#/components/schemas/group'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
      operationId: getGetGroupById
      x-operation-id-source: derived
  /create_group:
    post:
      tags:
      - Groups
      summary: Create a group
      description: 'Creates a new group. Adds the current user to the group by default.


        **Note**: group user parameters must be flattened into the format `users__{index}__{property}`, where

        `property` is `user_id`, `first_name`, `last_name`, or `email`.

        The user''s email or ID must be provided.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                group_type:
                  type: string
                  enum:
                  - home
                  - trip
                  - couple
                  - other
                  - apartment
                  - house
                  example: home
                  description: 'What is the group used for?


                    **Note**: It is recommended to use `home` in place of `house` or `apartment`.

                    '
                simplify_by_default:
                  type: boolean
                  description: Turn on simplify debts?
              additionalProperties:
                type: string
                x-additionalPropertiesName: users__{index}__{property}
              example:
                name: The Brain Trust
                group_type: trip
                users__0__first_name: Alan
                users__0__last_name: Turing
                users__0__email: alan@example.org
                users__1__id: 5823
              required:
              - name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  group:
                    $ref: '#/components/schemas/group'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      base:
                        type: array
                        items:
                          type: string
                          example: You cannot add unknown users to a group by user_id
      operationId: postCreateGroup
      x-operation-id-source: derived
  /delete_group/{id}:
    post:
      tags:
      - Groups
      summary: Delete a group
      description: Delete an existing group. Destroys all associated records (expenses, etc.)
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
      operationId: postDeleteGroupById
      x-operation-id-source: derived
  /undelete_group/{id}:
    parameters:
    - in: path
      name: id
      schema:
        type: integer
      required: true
    post:
      tags:
      - Groups
      summary: Restore a group
      description: 'Restores a deleted group.


        **Note**: 200 OK does not indicate a successful response. You must check the `success` value of the response.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                Success:
                  value:
                    success: true
                Failure:
                  value:
                    success: false
                    errors:
                    - You do not have permission to undelete this group.
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
      operationId: postUndeleteGroupById
      x-operation-id-source: derived
  /add_user_to_group:
    post:
      tags:
      - Groups
      summary: Add a user to a group
      description: '**Note**: 200 OK does not indicate a successful response. You must check the `success` value of the response.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                title: User ID
                properties:
                  group_id:
                    type: integer
                    example: 49012
                  user_id:
                    type: integer
                    example: 7999632
                required:
                - user_id
              - type: object
                title: User info
                properties:
                  group_id:
                    type: integer
                    example: 49012
                  first_name:
                    type: string
                    example: Grace
                  last_name:
                    type: string
                    example: Hopper
                  email:
                    type: string
                    example: gracehopper@example.com
                required:
                - first_name
                - last_name
                - email
              required:
              - group_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  user:
                    $ref: '#/components/schemas/user'
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
              examples:
                Success:
                  value:
                    success: true
                    user: {}
                    errors: {}
                Failure:
                  value:
                    success: false
                    user: null
                    errors:
                      base:
                      - That user cannot be a member of this group
      operationId: postAddUserToGroup
      x-operation-id-source: derived
  /remove_user_from_group:
    post:
      tags:
      - Groups
      summary: Remove a user from a group
      description: 'Remove a user from a group. Does not succeed if the user has a non-zero balance.


        **Note:** 200 OK does not indicate a successful response. You must check the success value of the response.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group_id:
                  type: integer
                  example: 4012
                user_id:
                  type: integer
                  example: 940142
              required:
              - user_id
              - group_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
              examples:
                Success:
                  value:
                    success: true
                    errors: {}
                Failure:
                  value:
                    success: false
                    errors:
                      base:
                      - The user has a non-zero balance
      operationId: postRemoveUserFromGroup
      x-operation-id-source: derived
components:
  responses:
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/forbidden'
    unauthorized:
      description: Invalid API key or OAuth access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/unauthorized'
    not_found:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/not_found'
  schemas:
    user:
      type: object
      properties:
        id:
          type: integer
        first_name:
          type: string
          example: Ada
        last_name:
          type:
          - string
          - 'null'
          example: Lovelace
        email:
          type: string
          example: ada@example.com
        registration_status:
          type: string
          enum:
          - confirmed
          - dummy
          - invited
        picture:
          type: object
          properties:
            small:
              type: string
            medium:
              type: string
            large:
              type: string
        custom_picture:
          type: boolean
          example: false
    debt:
      type: object
      properties:
        from:
          type: integer
          example: 18523
          description: User ID
        to:
          type: integer
          example: 90261
          description: User ID
        amount:
          type: string
          example: '414.5'
        currency_code:
          type: string
          example: USD
    forbidden:
      type: object
      properties:
        errors:
          type: object
          properties:
            base:
              type: array
              items:
                type: string
                example: 'Invalid API request: you do not have permission to perform that action'
    group:
      type: object
      properties:
        id:
          type: integer
          example: 321
        name:
          type: string
          example: Housemates 2020
        group_type:
          type: string
          enum:
          - home
          - trip
          - couple
          - other
          - apartment
          - house
          example: home
          description: 'What is the group used for?


            **Note**: It is recommended to use `home` in place of `house` or `apartment`.

            '
        updated_at:
          type: string
          format: date-time
        simplify_by_default:
          type: boolean
        members:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/user'
            - type: object
              properties:
                balance:
                  type: array
                  items:
                    type: object
                    properties:
                      currency_code:
                        type: string
                        example: USD
                      amount:
                        type: string
                        example: '-5.02'
        original_debts:
          type: array
          items:
            $ref: '#/components/schemas/debt'
        simplified_debts:
          type: array
          items:
            $ref: '#/components/schemas/debt'
        avatar:
          type: object
          properties:
            original:
              type:
              - string
              - 'null'
              example: null
            xxlarge:
              type: string
              example: https://s3.amazonaws.com/splitwise/uploads/group/default_avatars/avatar-ruby2-house-1000px.png
            xlarge:
              type: string
              example: https://s3.amazonaws.com/splitwise/uploads/group/default_avatars/avatar-ruby2-house-500px.png
            large:
              type: string
              example: https://s3.amazonaws.com/splitwise/uploads/group/default_avatars/avatar-ruby2-house-200px.png
            medium:
              type: string
              example: https://s3.amazonaws.com/splitwise/uploads/group/default_avatars/avatar-ruby2-house-100px.png
            small:
              type: string
              example: https://s3.amazonaws.com/splitwise/uploads/group/default_avatars/avatar-ruby2-house-50px.png
        custom_avatar:
          type: boolean
        cover_photo:
          type: object
          properties:
            xxlarge:
              type: string
              example: https://s3.amazonaws.com/splitwise/uploads/group/default_cover_photos/coverphoto-ruby-1000px.png
            xlarge:
              type: string
              example: https://s3.amazonaws.com/splitwise/uploads/group/default_cover_photos/coverphoto-ruby-500px.png
        invite_link:
          type: string
          example: https://www.splitwise.com/join/abQwErTyuI+12
          description: A link the user can send to a friend to join the group directly
    unauthorized:
      type: object
      properties:
        error:
          type: string
          example: 'Invalid API request: you are not logged in'
    not_found:
      type: object
      properties:
        errors:
          type: object
          properties:
            base:
              type: array
              items:
                type: string
                example: 'Invalid API Request: record not found'
  securitySchemes:
    OAuth:
      type: oauth2
      description: 'Splitwise uses OAuth 2 with the authorization code flow. To connect via OAuth 2, you''ll need to [register your app](https://secure.splitwise.com/apps). When you register, you''ll be given a key and secret.


        **Note**: OAuth can be a very confusing protocol to implement correctly, and we **strongly** recommend

        that you use an existing OAuth library to connect to Splitwise. You can find a list of OAuth client libraries at the

        [OAuth community site](https://oauth.net/code/#client-libraries).


        For more information on using OAuth, check out the following resources:


        - The OAuth community [getting started guide](https://oauth.net/getting-started/)

        - The oauth.com [OAuth 2.0 playground](https://www.oauth.com/playground/) (great for debugging authorization issues)

        - This [old Splitwise blog post](https://blog.splitwise.com/2013/07/15/setting-up-oauth-for-the-splitwise-api/) about OAuth

        '
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes: {}
    ApiKeyAuth:
      type: http
      description: 'For speed and ease of prototyping, you can generate a personal API key on your app''s details page. You should present this key to the server via the Authorization header as a Bearer token. The API key is an access token for your personal account, so keep it as safe as you would a password.

        If your key becomes compromised or you want to invalidate your existing key for any other reason, you can do so on the app details page by generating a new key.'
      scheme: bearer
      bearerFormat: API key