Splitwise Expenses API

openapi: 3.2.0
info:
  version: 3.0.0
  title: Splitwise Expenses 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: Expenses
  x-displayName: Expenses
paths:
  /get_expense/{id}:
    parameters:
    - in: path
      name: id
      schema:
        type: integer
      required: true
    get:
      tags:
      - Expenses
      summary: Get expense information
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  expense:
                    $ref: '#/components/schemas/expense'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
      operationId: getGetExpenseById
      x-operation-id-source: derived
  /get_expenses:
    get:
      tags:
      - Expenses
      summary: List the current user's expenses
      parameters:
      - in: query
        name: group_id
        schema:
          type: integer
        description: If provided, only expenses in that group will be returned, and `friend_id` will be ignored.
      - in: query
        name: friend_id
        schema:
          type: integer
        description: ID of another user. If provided, only expenses between the current and provided user will be returned.
      - in: query
        name: dated_after
        schema:
          type: string
          format: date-time
      - in: query
        name: dated_before
        schema:
          type: string
          format: date-time
      - in: query
        name: updated_after
        schema:
          type: string
          format: update-time
      - in: query
        name: updated_before
        schema:
          type: string
          format: date-time
      - in: query
        name: limit
        schema:
          type: integer
          default: 20
      - in: query
        name: offset
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  expenses:
                    type: array
                    items:
                      $ref: '#/components/schemas/expense'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
      operationId: getGetExpenses
      x-operation-id-source: derived
  /create_expense:
    post:
      tags:
      - Expenses
      summary: Create an expense
      description: 'Creates an expense. You may either split an expense equally (only with `group_id` provided),

        or supply a list of shares.


        When splitting equally, the authenticated user is assumed to be the payer.


        When providing a list of shares, each share must include `paid_share` and `owed_share`, and must be identified by one of the following:

        - `email`, `first_name`, and `last_name`

        - `user_id`


        **Note**: 200 OK does not indicate a successful response. The operation was successful only if `errors` is empty.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/equal_group_split'
                title: Equal group split
              - $ref: '#/components/schemas/by_shares'
                title: Split by shares
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  expenses:
                    type: array
                    items:
                      $ref: '#/components/schemas/expense'
                  errors:
                    type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    properties:
                      base:
                        type: array
                        items:
                          type: string
                          example: Unrecognized parameter `bad_parameter`
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
      operationId: postCreateExpense
      x-operation-id-source: derived
  /update_expense/{id}:
    post:
      tags:
      - Expenses
      summary: Update an expense
      description: 'Updates an expense. Parameters are the same as in `create_expense`, but you only need to include parameters

        that are changing from the previous values. If any values is supplied for `users__{index}__{property}`, _all_

        shares for the expense will be overwritten with the provided values.


        **Note**: 200 OK does not indicate a successful response. The operation was successful only if `errors` is empty.'
      parameters:
      - in: path
        name: id
        description: ID of the expense to update
        schema:
          type: integer
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/by_shares'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  expenses:
                    type: array
                    items:
                      $ref: '#/components/schemas/expense'
                  errors:
                    type: object
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
      operationId: postUpdateExpenseById
      x-operation-id-source: derived
  /delete_expense/{id}:
    post:
      tags:
      - Expenses
      summary: Delete an expense
      description: '**Note**: 200 OK does not indicate a successful response. The operation was successful only if `success` is true.'
      parameters:
      - in: path
        name: id
        description: ID of the expense to delete
        schema:
          type: integer
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  errors:
                    type: object
                required:
                - success
              examples:
                Success:
                  value:
                    success: true
                Failure:
                  value:
                    success: false
                    errors:
                      expense:
                      - does not exist, or has already been deleted
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
      operationId: postDeleteExpenseById
      x-operation-id-source: derived
  /undelete_expense/{id}:
    post:
      tags:
      - Expenses
      summary: Restore an expense
      description: '**Note**: 200 OK does not indicate a successful response. The operation was successful only if `success` is true.'
      parameters:
      - in: path
        name: id
        description: ID of the expense to restore
        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'
      operationId: postUndeleteExpenseById
      x-operation-id-source: derived
components:
  schemas:
    expense:
      allOf:
      - $ref: '#/components/schemas/common'
      - type: object
        properties:
          id:
            type: integer
            format: int64
            example: 51023
          group_id:
            type:
            - integer
            - 'null'
            example: 391
            description: Null if the expense is not associated with a group.
          friendship_id:
            type:
            - integer
            - 'null'
            example: 4818
            description: Null if the expense is not associated with a friendship.
          expense_bundle_id:
            type:
            - integer
            - 'null'
            example: 491030
          description:
            type: string
            example: Brunch
          repeats:
            type: boolean
            description: Whether the expense recurs automatically
          repeat_interval:
            type: string
            enum:
            - never
            - weekly
            - fortnightly
            - monthly
            - yearly
          email_reminder:
            type: boolean
            description: 'Whether a reminder will be sent to involved users in advance of the next occurrence of a recurring expense.

              Only applicable if the expense recurs.

              '
          email_reminder_in_advance:
            type:
            - integer
            - 'null'
            description: 'Number of days in advance to remind involved users about the next occurrence of a new expense.

              Only applicable if the expense recurs.

              '
            enum:
            - null
            - -1
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 14
          next_repeat:
            type:
            - string
            - 'null'
            description: The date of the next occurrence of a recurring expense. Only applicable if the expense recurs.
          details:
            type:
            - string
            - 'null'
            description: Also known as "notes."
          comments_count:
            type: integer
          payment:
            type: boolean
            description: Whether this was a payment between users
          transaction_confirmed:
            type: boolean
            description: If a payment was made via an integrated third party service, whether it was confirmed by that service.
          cost:
            type: string
            example: '25.0'
          currency_code:
            type: string
            example: USD
          repayments:
            type: array
            items:
              type: object
              properties:
                from:
                  type: integer
                  description: ID of the owing user
                  example: 6788709
                to:
                  type: integer
                  description: ID of the owed user
                  example: 270896089
                amount:
                  type: string
                  example: '25.0'
          date:
            type: string
            format: date-time
            description: The date and time the expense took place. May differ from `created_at`
            example: '2012-05-02T13:00:00Z'
          created_at:
            type: string
            format: date-time
            description: The date and time the expense was created on Splitwise
            example: '2012-07-27T06:17:09Z'
          created_by:
            allOf:
            - $ref: '#/components/schemas/user'
            - {}
          updated_at:
            type: string
            description: The last time the expense was updated.
            format: date-time
            example: '2012-12-23T05:47:02Z'
          updated_by:
            allOf:
            - $ref: '#/components/schemas/user'
            - {}
          deleted_at:
            type:
            - string
            - 'null'
            description: If the expense was deleted, when it was deleted.
            format: date-time
            example: '2012-12-23T05:47:02Z'
          deleted_by:
            allOf:
            - $ref: '#/components/schemas/user'
            - {}
          category:
            type: object
            properties:
              id:
                type: integer
                example: 5
              name:
                type: string
                example: Electricity
                description: Translated to the current user's locale
          receipt:
            type: object
            properties:
              large:
                type:
                - string
                - 'null'
                example: https://splitwise.s3.amazonaws.com/uploads/expense/receipt/3678899/large_95f8ecd1-536b-44ce-ad9b-0a9498bb7cf0.png
              original:
                type:
                - string
                - 'null'
                example: https://splitwise.s3.amazonaws.com/uploads/expense/receipt/3678899/95f8ecd1-536b-44ce-ad9b-0a9498bb7cf0.png
          users:
            type: array
            items:
              $ref: '#/components/schemas/share'
          comments:
            type: array
            items:
              $ref: '#/components/schemas/comment'
    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'
    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
    common:
      type: object
      properties:
        cost:
          type: string
          example: '25'
          description: A string representation of a decimal value, limited to 2 decimal places
        description:
          type: string
          description: A short description of the expense
          example: Grocery run
        details:
          type:
          - string
          - 'null'
          description: Also known as "notes."
        date:
          type: string
          description: The date and time the expense took place. May differ from `created_at`
          format: date-time
          example: '2012-05-02T13:00:00Z'
        repeat_interval:
          type: string
          enum:
          - never
          - weekly
          - fortnightly
          - monthly
          - yearly
        currency_code:
          type: string
          example: USD
          description: A currency code. Must be in the list from `get_currencies`
        category_id:
          type: integer
          description: A category id from `get_categories`
          example: 15
    equal_group_split:
      allOf:
      - $ref: '#/components/schemas/common'
      - type: object
        properties:
          group_id:
            type: integer
            description: The group to put this expense in.
          split_equally:
            type: boolean
            enum:
            - true
      - required:
        - group_id
        - split_equally
        - description
        - cost
    comment:
      type: object
      properties:
        id:
          type: integer
          example: 79800950
        content:
          type: string
          example: 'John D. updated this transaction: - The cost changed from $6.99 to $8.99'
        comment_type:
          type: string
          enum:
          - System
          - User
        relation_type:
          type: string
          enum:
          - ExpenseComment
        relation_id:
          type: integer
          example: 855870953
          description: ID of the subject of the comment
        created_at:
          type: string
          format: date-time
        deleted_at:
          type:
          - string
          - 'null'
          format: date-time
        user:
          $ref: '#/components/schemas/comment_user'
    by_shares:
      allOf:
      - $ref: '#/components/schemas/common'
      - type: object
        properties:
          group_id:
            type: integer
            description: The group to put this expense in, or `0` to create an expense outside of a group.
          users__0__user_id:
            type: integer
            example: 54123
          users__0__paid_share:
            type: string
            example: '25'
            description: Decimal amount as a string with 2 decimal places. The amount this user paid for the expense
          users__0__owed_share:
            type: string
            example: '13.55'
            description: Decimal amount as a string with 2 decimal places. The amount this user owes for the expense
          users__1__first_name:
            type: string
            example: Neu
          users__1__last_name:
            type: string
            example: Yewzer
          users__1__email:
            type: string
            example: neuyewxyz@example.com
          users__1__paid_share:
            type: string
            example: '0'
            description: Decimal amount as a string with 2 decimal places. The amount this user paid for the expense
          users__1__owed_share:
            type: string
            example: '11.45'
            description: Decimal amount as a string with 2 decimal places. The amount this user owes for the expense
        additionalProperties:
          x-additionalPropertiesName: users__{index}__{property}
          type: string
      - required:
        - group_id
        - description
        - cost
    unauthorized:
      type: object
      properties:
        error:
          type: string
          example: 'Invalid API request: you are not logged in'
    comment_user:
      type: object
      properties:
        id:
          type: integer
          example: 491923
        first_name:
          type: string
          example: Jane
        last_name:
          type: string
          example: Doe
        picture:
          type: object
          properties:
            medium:
              type: string
              example: image_url
    share:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/comment_user'
        user_id:
          type: integer
          example: 491923
        paid_share:
          type: string
          example: '8.99'
        owed_share:
          type: string
          example: '4.5'
        net_balance:
          type: string
          example: '4.49'
    not_found:
      type: object
      properties:
        errors:
          type: object
          properties:
            base:
              type: array
              items:
                type: string
                example: 'Invalid API Request: record not found'
  responses:
    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'
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/forbidden'
  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