splitwise.yaml

openapi: 3.0.1
info:
  version: 3.0.0
  title: Splitwise API
  x-logo:
    url: https://www.splitwise.com/assets/press/logos/sw.svg
    altText: Splitwise logo and name
  description: |
    # Introduction
    Hey there! We're glad you're interested in the Splitwise API. This documentation will help you to fetch information
    from the Splitwise app concerning users, expenses, groups, and much more. The terms governing your use of the API
    are provided below. **Please review them, as your use of the API is conditioned on your acceptance of those terms.
    If you do not agree with these Terms, you are not entitled to use the API.**

    If something in the API is confusing you, you can open an issue about it [on GitHub](https://github.com/splitwise/api-docs).
    We're a small team, so we may not have an instant fix, but we'll get back to you as soon as we're able.
    (If you spot an issue in our API documentation itself, feel free to open a pull request to update this website!)

    # Third-Party SDKs
    The development community has built a number of unofficial, third-party SDKs for Splitwise in a variety of different languages.

    - Dart
      - https://github.com/srthkpthk/splitwise_api
    - Elixir
      - https://github.com/matiasdelgado/ex_splitwise
    - Golang
      - https://github.com/anvari1313/splitwise.go
      - https://github.com/aanzolaavila/splitwise.go
    - Haskell
      - https://github.com/daniel-beard/splitwise-hs
    - Java
      - https://github.com/sritejakv/splitwise-java
    - Javascript
      - https://github.com/keriwarr/splitwise
      - https://github.com/Bearer/Pizzly
      - https://github.com/athulanilthomas/splitwise-ts
    - Python
      - https://github.com/namaggarwal/splitwise
    - Ruby
      - https://github.com/divyum/splitwise-ruby
    - Rust
      - https://github.com/pbar1/splitwise-rs

    If you've built a third-party SDK for Splitwise and you'd like to see it included in this list, then please open a pull request to update this section and add a new link. Thank you for your work!

    **Note**: These links are provided for convenience. These libraries have not been reviewed or endorsed by Splitwise, and Splitwise
    cannot vouch for their quality. If you have questions or bug reports, please direct your feedback to the authors of these libraries.

    # Terms of Use

    ## Overview

    Splitwise provides this self-serve API (the "Self-Serve API" or "API") to facilitate integrations with third-party applications, as well as open-up functionality for hobbyists and power users to programmatically interact with their own Splitwise account and build plugins or other tools.

    *The API is not intended for commercial use, as determined by Splitwise. Specifically, the API may not be used in connection with any fee-based service.*
    If you’re interested in integrating your commercial application with Splitwise, please contact developers@splitwise.com so our development team can help discuss your use case and offer an appropriate commercial license for the integration. The Self-Serve API documented here may be suitable for internal prototyping and other exploratory work, but it is not intended for any commercial implementation.

    Splitwise may impose conditions on the use of the Self-Serve API, including, for example, maintaining an active Splitwise Pro subscription.

    Please be aware that our Self-Serve API has conservative rate and access limits, which are subject to change at any time and not intended for commercial projects. If this is a problem for your use case, please contact us at developers@splitwise.com to discuss your needs.

    Any and all use of the Self-Service API is subject to the Terms of Use below.

    ## TERMS OF USE

    These API Terms of Use describe your rights and responsibilities when accessing our publicly available Application Programming Interface (API) and related API documentation. Please review them carefully.

    Splitwise may modify this Agreement at any time by posting a revised version on our website. The revised version will be effective at the time that it is posted. 

    These API terms form a binding contract between you and us. In these terms "you," and "your," refers to the individual, company or legal entity and/or entities that you represent while accessing the API. “We”, “us”, “our” and “Splitwise” refers to Splitwise Inc. By accepting these API terms, either by accessing or using the API, or authorizing or permitting any individual to access or use the API, you agree to be bound by this contract.

    <ol>
      <li>
        API License:
        <ol type="a">
          <li>
            Subject to the restrictions in these terms, we grant you a non-exclusive, revocable, worldwide, non-transferable, non-sublicensable, limited license to access and use (i) our APIs (ii) related API documentation, packages, sample code, software, or materials made available by Splitwise (“API Documentation”), and (iii) any and all access keys or data derived or obtained from Splitwise API responses (“Splitwise Data”). The Splitwise API, Splitwise Data, and API Documentation will be together referred to as the “Splitwise Materials.” You will use Splitwise Materials solely as necessary to develop, test, and support a permitted integration of your software application (an "Application" or "App") with Splitwise's services (the "Services") in accordance with this Agreement and any other agreements between you and Splitwise.
          </li>
        </ol>
      </li>
      <li>
        API License Restrictions
        <ol type="a">
          <li>
            You agree that will you will not, and will not allow any third party, including any of your partners, subsidiaries and/or affiliates and each of their respective directors, officers, employees, agents, partners, suppliers, service providers, contractors or end users (collectively, “Your Affiliates”) to engage in any Prohibited Activities set forth below.
          </li>
          <li>
            Splitwise reserves the right to block or revoke, with or without notice, your access to any or all of the Splitwise Materials for any reason including if Splitwise determines in its sole discretion that you are engaging in any of the Prohibited Activities.
          </li>
          <li>
            Splitwise may monitor your use of Splitwise Materials to improve our Services and ensure compliance with these Terms and may suspend your access to Splitwise Materials for any reason including if we believe you are in violation of these Terms.
          </li>
          <li>
            Your use of the Splitwise API is subject to usage limits and other functional restrictions established in the sole discretion of Splitwise. You will not use the API in a manner that exceeds rate limits or constitutes excessive or abusive usage, as determined by Splitwise.
          </li>
          <li>
            Your use of Splitwise Materials must respect each Splitwise user’s privacy choices and settings as well as the Privacy portion of these Terms. You will obtain explicit consent from end users as a basis for any processing of Splitwise Materials. Your use of Splitwise Materials must comply with all applicable data protection laws, including but not limited to the GDPR and CCPA.
          </li>
          <li>
            Prohibited Activities:
            <ol type="i">
              <li>
                You will not use Splitwise Materials or any part thereof in any manner or for any purpose that violates any law or regulation, or any right of any person, including but not limited to intellectual property rights, rights of privacy and/or publicity, or which otherwise results in liability to Splitwise, or its officers, employees, or any end user.
              </li>
              <li>
                You will not use Splitwise Materials in a way that poses a security, operational or technical risk to our Services.
              </li>
              <li>
                To the extent allowed by applicable law, you may not use Splitwise Materials to create an application that replicates existing Splitwise functionality or competes with Splitwise and our Services.
              </li>
              <li>
                You will not use Splitwise Materials to create an application that encourages or creates functionality for users to violate these Terms or our <a href="https://www.splitwise.com/terms">Terms of Service</a>.
              </li>
              <li>
                You will not use Splitwise Materials to create an application that can be used by anyone under the age of 13. You will not knowingly collect or enable the collection of any personal information from children under the age of 13.
              </li>
              <li>
                You will not reverse engineer, decompile, disassemble, or otherwise attempt to derive the source code or underlying ideas, trade secrets, algorithms or structure of the Splitwise Materials, or Splitwise software applications.
              </li>
              <li>
                You will not attempt to defeat, avoid, bypass, remove, deactivate or otherwise circumvent any software protection mechanisms in the Splitwise Materials or any part thereof, including without limitation, any such mechanism used to restrict or control the functionality of the API.
              </li>
              <li>
                You will not use Splitwise’s name to endorse or promote any product, including a product derived from Splitwise Materials.
              </li>
              <li>
                You will not sell, lease, rent, sublicense or in any way otherwise commercialize any Splitwise Data, or dataset derived from Splitwise Data and/or Splitwise Materials.
              </li>
              <li>
                You will not use Splitwise Materials in applications that send unsolicited communications to users or include any malware, adware, potentially unwanted programs, or similar applications that could damage or disparage Splitwise’s reputation or the Services.
              </li>
            </ol>
        </ol>
      </li>
      <li>
        Privacy
        <ol type="a">
          <li>
            Your Application must have a lawful privacy policy, accessible with reasonably prominent hyperlinks that does not conflict with or supersede the Splitwise Privacy Policy. Your privacy policy must explain how you collect, store, use, and/or transfer any Personal Data via your Applications. Personal Data is data that may be used, either alone or together with other information, to identify an individual user, including, without limitation, a user’s name, address, telephone number, username, email address, city and country, geolocation, unique identifiers, picture, or other similar information and includes personal data as defined in the GDPR.
          </li>
          <li>
            You are responsible for maintaining an appropriate legal basis to process any data under all applicable data protection laws (including but not limited to the GDPR and the CCPA).
          </li>
          <li>
            You will use industry standard security measures to protect against and prevent security breaches and any unauthorized disclosure of any personal information you process, including administrative, physical and technical safeguards for protection of the security, confidentiality and integrity of that personal information.
          </li>
          <li>
            You must promptly notify us in writing via email to security@splitwise.com of any known or suspected security deficiencies in, or intrusions to your Applications as well as any breaches of your user agreement or privacy policy that impact or may impact Splitwise customers. Please review our Privacy Statement for more information on how we collect and use data relating to the use and performance of our Service.
          </li>
          <li>
            You will delete Splitwise Data as requested within a reasonable time, if so requested by either a Splitwise user or Splitwise.
          </li>
          <li>
            All data submitted to Splitwise through your use of the Splitwise API will be governed by the Splitwise Privacy Statement.
          </li>
          <li>
            You agree that Splitwise may collect certain use data and information related to your use of the Splitwise Materials, and the API in connection with your Application (“Usage Data”), and that Splitwise may use such Usage Data for any business purpose, internal or external, including, without limitation, providing enhancements to the Materials or the Services, providing user support, or otherwise. You agree to include a statement to this effect in your Application’s Privacy Policy.
          </li>
        </ol>
      </li>

      <li>
        Conditions Of Use
        <ol type="a">
          <li>
            Splitwise reserves the right to modify our API at any time, for any reason, without notice.
          </li>
          <li>
            Splitwise may use your name, and other contact details to contact you regarding your use of our API or, if we believe you are in violation of these Terms.
          </li>
          <li>
            You are solely responsible for your use of the API and any application you create that uses Splitwise Materials, including but not limited to customer support.
          </li>
          <li>
            Splitwise reserves the right to develop and extend its products and capabilities without regard to whether those products compete with or invalidate your Splitwise integration or products offered by you.
          </li>
          <li>
            Splitwise may limit (i) the number of network calls that your App may make via the API; and (ii) the maximum number of Splitwise users that may connect your Application, or (iii) anything else about the Splitwise API as Splitwise deems appropriate, at Splitwise’s sole discretion.
          </li>
          <li>
            Splitwise may impose or modify these Terms and any other terms or conditions relating to your use of the API at any time for any reason with or without notice. Splitwise may utilize technical measures to prevent over-usage and stop usage of the API by your App after any usage limitations are exceeded or suspend your access to the API for any reason with or without notice.
          </li>
          <li>
            You will not issue any press release or other announcement regarding your Application that makes any reference to Splitwise without our prior written consent.
          </li>
          <li>
            You will not use our API to distribute unsolicited advertising or promotions, or to send messages, make comments, or initiate any other unsolicited direct communication or contact with Splitwise users or partners.
          </li>
        </ol>
      </li>

      <li>
        Use of Splitwise Marks
        <ol type="a">
          <li>
            The rights granted in this Agreement do not include any right to use the Splitwise name or any Splitwise trademarks, service marks or logos (the “Splitwise Marks”) with respect to your Applications. Subject to your continued compliance with this Agreement, you may use the "Splitwise" name solely for the purpose of describing your applications. Any other use of the Splitwise name or Splitwise Marks must be agreed to by Splitwise in writing.
          </li>
          <li>
            These rights apply on a non-exclusive, non-transferable, worldwide, royalty-free basis, without any right to sub-license, and may be revoked by Splitwise at any time.
          </li>
          <li>
            If Splitwise updates its branding guidelines or any Splitwise Marks that you are using, you agree to update such Splitwise Marks to reflect the most current versions. You must not use any Splitwise Marks or trade dress, or any confusingly similar mark or trade dress, as the name or part of the name, user interface, or icon of your Applications, or as part of any logo or branding for your Applications.
          </li>
        </ol>
      </li>

      <li>
        Reservation Of Rights. The Splitwise Materials as well as the trademarks, copyrights, trade secrets, patents or other intellectual property (collectively, “Intellectual Property”) contained therein will remain the sole and exclusive property of Splitwise. Splitwise reserves to itself all rights to the Splitwise Materials not expressly granted to You. Except as expressly provided in this Agreement, you do not acquire any rights to or interest in the Intellectual Property. You will not utilize Splitwise Intellectual Property except as expressly authorized under this Agreement.
      </li>

      <li>
        Feedback. Splitwise welcomes feedback from developers to improve our API, documentation and Services, and may provide feedback to you as well. We will review any feedback received, however we make no guarantee that suggestions will be implemented. If you choose to provide feedback, suggestions or comments regarding the Splitwise API, documentation, or Services, you acknowledge that Splitwise will be free to use your feedback in any way it sees fit. This includes the freedom to copy, modify, create derivative works, distribute, publicly display, publicly perform, grant sublicenses to, and otherwise exploit in any manner such feedback, suggestions or comments, for any and all purposes, with no obligation of any kind to you, in perpetuity.
      </li>

      <li>
        Confidentiality. Any information not generally available to the public that is made available to you should be considered confidential. You agree to:
        <ol type="a">
          <li>
            Protect this information from unauthorized use, access, or disclosure, 
          </li>
          <li>
            Use this information only as necessary,
          </li>
          <li>
            Destroy any copies, or return this information to us when your use of the API is terminated, or at any time as requested by Splitwise
          </li>
        </ol>
      </li>

      <li>
        Termination. These Terms shall remain effective until terminated by either party. You may terminate these Terms at any time, by discontinuing your use of our APIs. Splitwise may terminate these Terms at any time with or without cause and without advanced notice to you. Upon termination, all rights and licenses granted under these Terms shall immediately terminate. You must immediately discontinue any use, and destroy any copies of the Splitwise Materials and Confidential information in your possession.
      </li>
      <li>
        Representations and Warranties. You represent and warrant that you have the legal power to accept these Terms, and that doing so will not violate any law or third party rights.
        <br><br>THE SPLITWISE API AND ANY RELATED SERVICES ARE BEING PROVIDED TO YOU ‘AS IS’ AND ‘AS AVAILABLE’ WITHOUT ANY WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF MERCHANTABILITY, TITLE, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. YOU ACKNOWLEDGE THAT WE DO NOT WARRANT THAT THE APIS OR THE SERVICES WILL BE UNINTERRUPTED, TIMELY, SECURE, OR ERROR-FREE.
      </li>
      <li>
        Limitation of Liability.
        <br><br>TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL SPLITWISE, ITS AFFILIATES, OFFICERS, DIRECTORS, EMPLOYEES, AGENTS, LICENSORS, LICENSEES, ASSIGNS OR SUCCESSORS BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY INDIRECT, INCIDENTAL, SPECIAL, PUNITIVE OR CONSEQUENTIAL DAMAGES (INCLUDING BUT NOT LIMITED TO ANY LOSS OF DATA, SERVICE INTERRUPTION, COMPUTER FAILURE, OR PECUNIARY LOSS) HOWEVER CAUSED, WHETHER IN CONTRACT, TORT OR UNDER ANY OTHER THEORY OF LIABILITY, AND WHETHER OR NOT YOU OR THE THIRD PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. YOUR ONLY RIGHT WITH RESPECT TO ANY PROBLEMS OR DISSATISFACTION WITH THE SPLITWISE SERVICES IS TO STOP USING THE SPLITWISE SERVICES.
        <br><br>SOME JURISDICTIONS DO NOT ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY FOR CERTAIN TYPES OF DAMAGES REFERRED TO ABOVE (INCLUDING INCIDENTAL OR CONSEQUENTIAL DAMAGES). ACCORDINGLY, SOME OF THE ABOVE LIMITATIONS AND EXCLUSIONS MAY NOT APPLY TO YOU. YOU AGREE THAT SPLITWISE’S AGGREGATE LIABILITY UNDER THIS AGREEMENT FOR BOTH DIRECT AND ANY INDIRECT DAMAGES AVAILABLE TO YOU IS LIMITED TO ONE HUNDRED DOLLARS ($100).
      </li>

      <li>
        Indemnification: If so requested by Splitwise, you agree to defend, indemnify, and hold harmless Splitwise and its affiliates, directors, and customers, from and against any and all third-party claims, actions, suits, and proceedings (including, but not limited to legal, or investigative fees), arising out of, or related to your use of the Services, your violation of these Terms, your violation of your user agreement or privacy policy, or your violation of any laws, regulations, or third party rights.
      </li>

      <li>
        Miscellaneous
        <ol type="a">
          <li>
            Applicable Law, Jurisdiction, and Venue: Any dispute arising out of this Agreement shall be governed by Massachusetts law and controlling U.S. federal law, without regard to conflict of law provisions thereof. Any claim or dispute between you and Splitwise that arises in whole or in part from these Terms or your use of the API or our Services shall be decided exclusively by a court of competent jurisdiction located in Massachusetts, and you hereby consent to, and waive all defenses of lack of personal jurisdiction and forum non conveniens with respect to venue and jurisdiction in the state and federal courts of Massachusetts.
          </li>
          <li>
            Assignment: You may not assign or delegate any of your rights or obligations hereunder, whether by operation of law or otherwise, without Splitwise’s prior written consent. Splitwise retains the right to assign these Terms in its entirety, without consent of the other party, to a corporate affiliate or in connection with a merger, acquisition, corporate reorganization, or sale of all or substantially all of its assets. Any purported assignment in violation of this section is void.
          </li>
          <li>
            Language: This contract was drafted in English. In the event that this contract, or any part thereof, is translated to a language other than English, the English-language version shall control in the event of a conflict.
          </li>
          <li>
            Relationship: You and Splitwise are independent contractors. These Terms do not create or imply any partnership, agency, joint venture, fiduciary or employment relationship between the parties. There are no third party beneficiaries to these Terms.
          </li>
          <li>
            Severability: These Terms will be enforced to the fullest extent permitted under applicable law. If any provision of these Terms is found to be invalid or unenforceable by a court of competent jurisdiction, the provision will be modified by the court and interpreted so as best to accomplish the objectives of the original provision to the fullest extent permitted by law, and the remaining provisions of these Terms will remain in effect.
          </li>
          <li>
            Force Majeure: Neither we nor you will be responsible for any failure to perform obligations under these Terms if such failure is caused by events beyond the reasonable control of a party, which may include denial-of-service attacks, a failure by a third party hosting provider, acts of God, war, strikes, revolutions, lack or failure of transportation facilities, laws or governmental regulations.
          </li>
          <li>
            Entire Agreement:  These Terms comprise the entire agreement between you and Splitwise with respect to the above subject matter and supersedes and merges all prior proposals, understandings and contemporaneous communications.
          </li>
        </ol>
      </li>
    </ol>

    # Rate Limits

    The Splitwise API is rate-limited to protect the stability of our service for all users. Rate limits vary by
    endpoint and resource, and are subject to change at any time without notice.

    If you make too many requests in a short period, the API will respond with an `HTTP 429 Too Many Requests`
    status code. When you receive a `429`, you should slow down the rate at which you're making requests and retry
    after a short delay.

    In practice, our rate limits are fairly lenient, and almost no hobby integration has ever exceeded them. If you're
    building a non-commercial plugin or personal project, you're very unlikely to run into these limits under normal
    use. If you have a use case that requires higher limits, or you're building a commercial integration, please reach
    out to us at developers@splitwise.com to discuss your needs.

servers:
  - url: 'https://secure.splitwise.com/api/v3.0'
    variables: {}
security:
  - OAuth: []
  - ApiKeyAuth: []
tags:
  - name: users
    x-displayName: Users
    description: Resources to access and modify user information.
  - 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.
  - name: friends
    x-displayName: Friends
  - name: expenses
    x-displayName: Expenses
  - name: comments
    x-displayName: Comments
  - name: notifications
    x-displayName: Notifications
  - name: other
    x-displayName: Other
paths:
  $ref: ./paths/index.yaml

components:
  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
  responses:
    Unauthorized:
      $ref: ./responses/unauthorized.yaml
    Forbidden:
      $ref: ./responses/forbidden.yaml
    Not_Found:
      $ref: ./responses/not_found.yaml
  schemas:
    Debt:
      $ref: ./schemas/debt.yaml
    User:
      $ref: ./schemas/user.yaml
    CurrentUser:
      $ref: ./schemas/current_user.yaml
    NotificationSettings:
      $ref: ./schemas/notification_settings.yaml
    Group:
      $ref: ./schemas/group.yaml
    UnauthorizedError:
      $ref: ./schemas/errors/unauthorized.yaml
    ForbiddenError:
      $ref: ./schemas/errors/forbidden.yaml
    NotFoundError:
      $ref: ./schemas/errors/not_found.yaml