diff --git a/source/includes/_comments.md b/source/includes/_comments.md index 7ce04fd..bcfa572 100644 --- a/source/includes/_comments.md +++ b/source/includes/_comments.md @@ -1,3 +1,57 @@ # Comments -## get_comments?expense_id= +## get_comments?expense_id=:id + +```json +{ + "comments": [ + { + "id": 79800950, + "content": "Something about this expense", + "comment_type": "User", + "relation_type": "ExpenseComment", + "relation_id": 855870953, + "created_at": "2020-05-14T04:12:25Z", + "deleted_at": null, + "user": { /* */ } + } + ] +} +``` + +`GET https://secure.splitwise.com/api/v3.0/get_comments?expense_id=:id` + +## create_comment + +```json +{ + "comment": { /* */ }, + "errors": {} +} +``` + +`POST https://secure.splitwise.com/api/v3.0/create_comment` + +### Query parameters + +Parameter | Type | Description +--------- | ---- | ----------- +expense_id | Integer | The expense the comment is for +content | String | The comment contents + +## delete_comment + +```json +{ + "comment": { /* */ }, + "errors": {} +} +``` + +`POST https://secure.splitwise.com/api/v3.0/delete_comment/:id` + +### Query parameters + +Parameter | Type | Description +--------- | ---- | ----------- +id | Integer | The comment id diff --git a/source/includes/_expenses.md b/source/includes/_expenses.md index 9838ad8..c0ee5d7 100644 --- a/source/includes/_expenses.md +++ b/source/includes/_expenses.md @@ -1,14 +1,179 @@ # Expenses +## get_expense/:id + +Return full details on an expense involving the current user. There are some additional values included in the expense object than shown here but they should be ignored. + +```json +{ + "expense": { + "id": 368887, + "group_id": 18417, //or null + "description": "Grocery run", + "repeats": false, + "repeat_interval": "never", //or "weekly", "fortnightly", "monthly", "yearly" + "email_reminder": false, + "email_reminder_in_advance": -1, // or 0, 1, 3, 5, 7, 14 + "next_repeat": null, + "details": "Additional notes about the expense", + "comments_count": 0, + "payment": false, + "transaction_confirmed": false, + "cost": "25.0", + "currency_code": "USD", + "repayments": [ + { + "from": 6788709, + "to": 270896089, + "amount": "25.0" + } + ], + "date": "2012-07-27T06:17:09Z", + "created_at": "2012-07-27T06:17:09Z", + "created_by": { /* */ }, + "updated_at": "2012-12-23T05:47:02Z", + "updated_by": { /* */ }, + "deleted_at": "2012-12-23T05:47:02Z", + "deleted_by": { /* */ }, + "category": { + "id": 18, + "name": "General" + }, + "receipt": { + "large": "https://splitwise.s3.amazonaws.com/uploads/expense/receipt/3678899/large_95f8ecd1-536b-44ce-ad9b-0a9498bb7cf0.png", + "original": "https://splitwise.s3.amazonaws.com/uploads/expense/receipt/3678899/95f8ecd1-536b-44ce-ad9b-0a9498bb7cf0.png" + }, + "users": [ + { + "user": { /* */ }, + "user_id": 270896089, + "paid_share": "25.0", + "owed_share": "0.0", + "net_balance": "25.0" + }, + { + "user": { /* */ }, + "user_id": 6788709, + "paid_share": "0.0", + "owed_share": "25.0", + "net_balance": "-25.0" + } + ], + "comments": [ /* , ,... */ ] + } +} +``` + +`GET https://secure.splitwise.com/api/v3.0/get_expense/:id` + ## get_expenses -## get_expense/:id +Return expenses involving the current user, in reverse chronological order + +```json +{ + "expenses": [ /* , , ... */ ], +} +``` + +`GET https://secure.splitwise.com/api/v3.0/get_expenses` + +### Query parameters + + + +Parameter | Type | Description +--------- | ---- | ----------- +group_id | Integer | Return expenses for specific group +friend_id | Integer | Return expenses for a specific friend that are not in any group +dated_after | Time | ISO 8601 Date time. Return expenses later that this date +dated_before | Time | ISO 8601 Date time. Return expenses earlier than this date +updated_after | Time | ISO 8601 Date time. Return expenses updated after this date +updated_before | Time | ISO 8601 Date time. Return expenses updated before this date +limit | Integer | How many expenses to fetch. Defaults to 20; set to 0 to fetch all +offset | Integer | Return expenses starting at limit * offset ## create_expense +```json +{ + "expense": { /* */ }, + "errors": { } +} +``` + +`POST https://secure.splitwise.com/api/v3.0/create_expense` + +### Query parameters + +#### Required + +Parameter | Type | Description +--------- | ---- | ----------- +cost | String | A string representation of a decimal value, limited to 2 decimal places +description | String | A short description of the expense +payment | Boolean | `true` if this is a payment, `false` otherwise + +#### Split configuration + + + +Parameter | Type | Description +--------- | ---- | ----------- +group_id | Integer | The group to put this expense in. +split_equally | Boolean | Set this to `true` if using it +user\__0\__id | Integer | The user id of a friend for this share +user\__0\__paid_share | String | Decimal amount as a string with 2 decimal places. The amount this user paid for the expense +user\__0\__owed_share | String | Decimal amount as a string with 2 decimal places. The amount this user owes on the expense +user\__1\__first_name | String | +user\__1\__last_name | String | +user\__1\__email | String | Valid email address for this user +user\__1\__paid_share | String | Decimal amount as a string with 2 decimal places. The amount this user paid for the expense +user\__1\__owed_share | String | Decimal amount as a string with 2 decimal places. The amount this user owes on the expense +user\__*\__key_value | String | Add additional user shares with indexes 2,3,4,5,... + +#### Optional parameters + +Parameter | Type | Description +--------- | ---- | ----------- +group_id | Integer | The group to put the expense in +details | String | More detailed notes +date | Time | ISO 8601 date time +repeat_interval | String | One of: never, weekly, fortnightly, monthly, yearly +currency_code | String | ISO 4217 currency code. Must be in the list from `get_currencies` +category_id | Integer | A category id from `get_categories` + ## update_expense/:id +```json +{ + "expense": { /* */ }, + "errors": { } +} +``` + +`POST https://secure.splitwise.com/api/v3.0/update_expense/:id` + +### Query parameters + +These are the same as for `create_expense` except you only need to include parameters that are changing from the previous values. + ## delete_expense/:id +```json +{ + "success": true, //or false +} +``` + +`POST https://secure.splitwise.com/api/v3.0/delete_expense/:id` + ## undelete_expense/:id +```json +{ + "success": true, //or false +} +``` + +`POST https://secure.splitwise.com/api/v3.0/undelete_expense/:id` diff --git a/source/includes/_friends.md b/source/includes/_friends.md index 30c6654..e0d88f1 100644 --- a/source/includes/_friends.md +++ b/source/includes/_friends.md @@ -166,10 +166,10 @@ Make the current user a friend of the specified users. Parameter | Type | Description --------- | ---- | ----------- -friends__0__user_first_name | String | Add a user's first name -friends__0__user_last_name | String | Add a user's last name -friends__0__user_email | String | Add a user's email (or find an existing user by email) -friends__1__user_email | String | Find an existing user by email) +friends\__0\__user_first_name | String | Add a user's first name +friends\__0\__user_last_name | String | Add a user's last name +friends\__0\__user_email | String | Add a user's email (or find an existing user by email) +friends\__1\__user_email | String | Find an existing user by email) ## delete_friend/:id diff --git a/source/includes/_groups.md b/source/includes/_groups.md index 8f26722..ef0e13b 100644 --- a/source/includes/_groups.md +++ b/source/includes/_groups.md @@ -10,11 +10,11 @@ A Group represents a collection of users who share expenses together. For exampl { "groups":[ // Non-group expenses are listed in a group with id 0 - { + { "id":0, "name":"Non-group expenses", "updated_at": "2017-08-30T20:31:51Z", // - "members":[ + "members":[ { "id": 1, "first_name": "Ada", @@ -26,29 +26,29 @@ A Group represents a collection of users who share expenses together. For exampl }, "email": "ada@example.com", "registration_status": "confirmed", //'dummy', 'invited', or 'confirmed' - "balance":[ - { + "balance":[ + { "currency_code":"AED", "amount":"0.0" }, - { + { "currency_code":"ALL", "amount":"0.0" }, - { + { "currency_code":"EUR", "amount":"-5.0" }, - { + { "currency_code":"USD", "amount":"3730.5" } //, ... ] - } // , ... - ], + } // , ... + ], "simplify_by_default":false, - "original_debts":[ - { + "original_debts":[ + { "from": 12345, // user_id "to": 54321, // user_id "amount":"414.5", // amount as a decimal string @@ -56,22 +56,22 @@ A Group represents a collection of users who share expenses together. For exampl } // , ... ] }, - { + { "id":3018312, "name":"a test group", "updated_at":"2017-08-30T20:31:51Z", - "members":[ /* , , ... */ ], + "members":[ /* , , ... */ ], "simplify_by_default":false, - "original_debts":[ - { + "original_debts":[ + { "from": 12345, // user_id "to": 54321, // user_id "amount":"414.5", // amount as a decimal string "currency_code":"USD" // three-letter currency code } // , ... ], - "simplified_debts":[ - { + "simplified_debts":[ + { "from": 12345, // user_id "to": 54321, // user_id "amount":"414.5", // amount as a decimal string @@ -96,22 +96,22 @@ Returns list of all groups that the current_user belongs to ```json { "group": - { + { "id":3018312, "name":"a test group", "updated_at":"2017-08-30T20:31:51Z", - "members":[ /* , , ... */ ], + "members":[ /* , , ... */ ], "simplify_by_default":false, - "original_debts":[ - { + "original_debts":[ + { "from": 12345, // user_id "to": 54321, // user_id "amount":"414.5", // amount as a decimal string "currency_code":"USD" // three-letter currency code } // , ... ], - "simplified_debts":[ - { + "simplified_debts":[ + { "from": 12345, // user_id "to": 54321, // user_id "amount":"414.5", // amount as a decimal string @@ -136,11 +136,11 @@ Returns information about the specified group (as long as the current user has a ```json { "group": - { + { "id":3018312, "name":"a test group", "updated_at":"2017-08-30T20:31:51Z", - "members":[ /* , , ... */ ], + "members":[ /* , , ... */ ], "simplify_by_default":false, "original_debts":[], "simplified_debts":[], @@ -161,19 +161,19 @@ Create a new group. Adds the current user to the group by default. - + Parameter | Type | Description --------- | ---- | ----------- name | String | Group name -whiteboard | String | Text to display on the group whiteboard -group_type | String | What the group is being used for (apartment, trip, couple, etc.) -simplify_by_default| Boolean | Turn on simplify debts? -users__0__first_name | String | Add a user's first name -users__0__last_name | String | Add a user's last name -users__0__email | String | Add a user's email -users__1__user_id | Integer | Add an existing user by id +whiteboard | String | Text to display on the group whiteboard +group_type | String | What the group is being used for (apartment, trip, couple, etc.) +simplify_by_default | Boolean | Turn on simplify debts? +users\__0\__first_name | String | Add a user's first name +users\__0\__last_name | String | Add a user's last name +users\__0\__email | String | Add a user's email +users\__1\__user_id | Integer | Add an existing user by id ## delete_group/:id @@ -181,7 +181,8 @@ users__1__user_id | Integer | Add an existing user by id ```json { - "success": true // or false + "success": true, // or false + "errors": ["any errors"] } ``` @@ -195,11 +196,13 @@ Delete an existing group. Destroys all associated records (expenses, etc.) > Example Response: ```json +{ + "success": true, //or false + "errors": ["any errors"] +} ``` -`` - -Desc: +`POST https://secure.splitwise.com/api/v3.0/undelete_group/:id` ## add_user_to_group @@ -222,7 +225,7 @@ Add a user to a group Parameter | Type | Description --------- | ---- | ----------- -group_id | Integer | Existing group to add the user to +group_id | Integer | Existing group to add the user to first_name | String | Add a user's first name last_name | String | Add a user's last name email | String | Add a user's email diff --git a/source/includes/_notifications.md b/source/includes/_notifications.md index dd15897..b25780a 100644 --- a/source/includes/_notifications.md +++ b/source/includes/_notifications.md @@ -1,3 +1,58 @@ # Notifications ## get_notifications + +```json +{ + "notifications": [ + { + "id": 32514315, + "type": 0, + "created_at": "2020-05-13T20:58:17Z", + "created_by": 2, + "source": { + "type": "Expense", + "id": 865077, + "url": null + }, + "image_url": "https://s3.amazonaws.com/splitwise/uploads/notifications/v2/0-venmo.png", + "image_shape": "square", + "content": "You paid Jon H..
You paid $23.45" + } //, ... + ] +} +``` + +`GET https://secure.splitwise.com/api/v3.0/get_notifications` + +Return a list of recent activity on the users account with the most recent items first. `content` will be suitable for display in HTML and uses only the ``, ``, ``, `
` and `` tags. + +The `type` value indicates what the notification is about. Notification `type`s may be added in the future without warning. Below is an incomplete list of notification types. + +Type | Meaning +---- | ------- +0 | Expense added +1 | Expense updated +2 | Expense deleted +3 | Comment added +4 | Added to group +5 | Removed from group +6 | Group deleted +7 | Group settings changed +8 | Added as friend +9 | Removed as friend +10 | News (a URL should be included) +11 | Debt simplification +12 | Group undeleted +13 | Expense undeleted +14 | Group currency conversion +15 | Friend currency conversion + +### Query parameters + + + +Parameter | Type | Description +--------- | ---- | ----------- +updated_after | Time | ISO 8601 Date and time string with timezone offset. Return notifications after this time. +limit | Integer | How many notifications to fetch. Defaults to 20. 0 for all. diff --git a/source/includes/_other.md b/source/includes/_other.md index 6e33536..f099a6c 100644 --- a/source/includes/_other.md +++ b/source/includes/_other.md @@ -136,7 +136,7 @@ { "currency_code":"VUV", "unit":"Vt" }, { "currency_code":"BTN", "unit":"Nu." }, { "currency_code":"WST", "unit":"WS$" } - ] } + ] } ``` `GET https://secure.splitwise.com/api/v3.0/get_currencies` @@ -145,5 +145,85 @@ Returns a list of all currencies allowed by the system. These are mostly ISO 42 ## get_categories +```json +{ + "categories": [ + { + "id": 19, + "name": "Entertainment", + "icon": "https://s3.amazonaws.com/splitwise/uploads/category/icon/square/entertainment/other.png", + "icon_types": { + "slim": { + "small": "https://s3.amazonaws.com/splitwise/uploads/category/icon/slim/entertainment/other.png", + "large": "https://s3.amazonaws.com/splitwise/uploads/category/icon/slim/entertainment/other@2x.png" + }, + "square": { + "large": "https://s3.amazonaws.com/splitwise/uploads/category/icon/square_v2/entertainment/other@2x.png", + "xlarge": "https://s3.amazonaws.com/splitwise/uploads/category/icon/square_v2/entertainment/other@3x.png" + } + }, + "subcategories": [ + { + "id": 20, + "name": "Games", + "icon": "https://s3.amazonaws.com/splitwise/uploads/category/icon/square/entertainment/games.png", + "icon_types": { + "slim": { + "small": "https://s3.amazonaws.com/splitwise/uploads/category/icon/slim/entertainment/games.png", + "large": "https://s3.amazonaws.com/splitwise/uploads/category/icon/slim/entertainment/games@2x.png" + }, + "square": { + "large": "https://s3.amazonaws.com/splitwise/uploads/category/icon/square_v2/entertainment/games@2x.png", + "xlarge": "https://s3.amazonaws.com/splitwise/uploads/category/icon/square_v2/entertainment/games@3x.png" + } + } + }, + { + "id": 21, + "name": "Movies", + "icon": "https://s3.amazonaws.com/splitwise/uploads/category/icon/square/entertainment/movies.png", + "icon_types": { + "slim": { + "small": "https://s3.amazonaws.com/splitwise/uploads/category/icon/slim/entertainment/movies.png", + "large": "https://s3.amazonaws.com/splitwise/uploads/category/icon/slim/entertainment/movies@2x.png" + }, + "square": { + "large": "https://s3.amazonaws.com/splitwise/uploads/category/icon/square_v2/entertainment/movies@2x.png", + "xlarge": "https://s3.amazonaws.com/splitwise/uploads/category/icon/square_v2/entertainment/movies@3x.png" + } + } + } //, ... + ] + } //, ... + ] +} +``` + +`GET https://secure.splitwise.com/api/v3.0/get_categories` + +Returns a list of all categories Splitwise allows for expenses. There are parent categories that represent groups of categories with subcategories for more specific categorization. You may not use the parent categories when creating expenses. If you intend for an expense to be represented by the parent category and nothing more specific, please use the `"Other"` subcategory. + ## parse_sentence +```json +{ + "expense": { /* */ }, + "valid": true, //or false + "error": "an error message" +} +``` + +`POST https://secure.splitwise.com/api/v3.0/parse_sentence` + +Attempts to create an expense from the `input` as an English natural language phrase like `"groceries $20"` or `"Jon paid me $50"`. If `valid` is `true`, the `expense` value will be a complete and valid expense. If it is `false`, the `expense` value may be missing some values. + +### Query Parameters + + + +Parameter | Type | Description +--------- | ---- | ----------- +input | String | A natural language sentence describing an expense +group_id | Integer | A group id +friend_id | Integer | A friend id +autosave | Boolean | If true, will save the resulting expense if valid. Defaults to false. diff --git a/source/index.html.md b/source/index.html.md index 97243d7..e243647 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -29,9 +29,6 @@ Hey there! We're glad you're interested in the Splitwise API. This documentation If something in the API is confusing you, you can open an [issue](https://github.com/splitwise/api-docs/issues) about it on GitHub. 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](https://github.com/splitwise/api-docs/pulls) 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.