API documentation

Introduction

The API provides programmatic access to create and manipulate bills, register payments and view settlements. This documentation describes the API, and how you can use it to integrate the service with your own applications or services.

Please note that the API is currently in beta, and may be subject to periodic change.

Design

The API is based on the principles of Representational State Transfer, and uses standard HTTP for communication.

The API returns data using JavaScript Object Notation, which can be easily parsed and manipulated in most popular programming languages, such as Python, Java, C# and Ruby. Be sure to set the HTTP Accept header to application/json to ensure you receive a JSON encoded response.

Methods that retrieve data from the service use HTTP GET requests, while methods that potentially change data (such as adding, editing or deleting objects) use POST requests. PUT and DELETE operations are currently not supported.

Examples and client libraries

We provide a Python client library that serves as a thin wrapper over the REST interface, and can be used freely in your projects.

If your system has curl installed, you can easily test the API from the command line.

  • List the user's bills:
    curl -u username:password -H 'Accept: application/json' http://shareabill.com/bills/

Authentication

All operations execute in the context of a signed in user. For example, invoking a method to list all bills only return the bills that belong to the signed in user.

Applications or services that use the API use HTTP Basic authentication to authenticate requests against the service. When authenticating, use the user's e-mail address as the username component.

You can use all regular user accounts with the API, but normal accounts may be subject to some additional limitations. To access the API without these limitations, please ask us for a dedicated API account. Applications and services using API accounts may also get additional branding in the user interface.

Methods

Bills

Bills are the central object in the service, and contains participants, expenses, payments and messages. Bills are uniquely identified by an ID field called a slug, which is passed in the URL of the methods that deal with specific bills.

List user's bills

Returns a list of all of the signed-in user's bills. This includes both bills that the signed in user has created, as well as bills the user is a participant in.

URL: http://shareabill.com/bills/

Method(s): GET

Returns: HTTP 200, and JSON-encoded list of bills

Parameters: None

Get a bill

Returns information about the bill with the given slug.

This is the preferred method to retrieve updated information about participants, expenses, settlement, payments and messages in the bill.

URL: http://shareabill.com/bills/<SLUG>/

Method(s): GET

Returns: HTTP 200, and JSON-encoded bill

Parameters: None

Add bill

Adds a new bill with the specified title and description.

URL: http://shareabill.com/bills/add/

Method(s): POST

Returns: HTTP 302 with redirect to bill URL

Parameters:

  • title: The new bill's title
  • description: The new bill's description

Update bill

Updates the bill with the specified data. Please note that all fields will be updated on each request, so you must include all fields even if they should remain unchanged.

URL: http://shareabill.com/bills/<SLUG>/update/

Method(s): POST

Returns: HTTP 200, and JSON-encoded bill

Parameters:

  • title: The new bill's title
  • description: The new bill's description
  • notification: Code indicating what notifications to send
  • reminder_interval: Days between sending of reminders
  • background: Title of custom background image

Remove bill

Removes the bill with the specified slug.

URL: http://shareabill.com/bills/<SLUG>/remove/

Method(s): POST

Returns: HTTP 302 with redirect to bills list

Parameters: None

Participants

Register participant

Registers a participant in the system. All participants must be registered before they can be added to a bill.

Calling this method is also required to add existing participants to a bill, since it is needed to retrieve the participant ID. Existing participants are matched based on the email address, so you can safely call this method with existing participants.

URL: http://shareabill.com/participants/add/

Method(s): POST

Returns: HTTP 200, and JSON-encoded participant

Parameters:

  • name: Name of the participant
  • email: The participant's email address
  • payment_info: Payment information for participant

Add participant to bill

Adds the a participant (registered or looked up with /participants/add/) to the specified bill.

URL: http://shareabill.com/bills/<SLUG>/participants/add/

Method(s): POST

Returns: HTTP 200, and JSON-encoded bill

Parameters:

  • participant: ID of the participant to add
  • send_invitation: Boolean indicating whether an automatic e-mail invitation should be sent

Remove participant from bill

Removes the a participant from the specified bill.

URL: http://shareabill.com/bills/<SLUG>/participants/remove/

Method(s): POST

Returns: HTTP 200, and JSON-encoded bill

Parameters:

  • participant: ID of the participant to remove

Expenses

Add expense to bill

Adds the specified expense to the bill.

URL: http://shareabill.com/bills/<SLUG>/expenses/add/

Method(s): POST

Returns: HTTP 200, and JSON-encoded bill

Parameters:

  • description: Expense description
  • amount: The amount paid for the expense
  • paid_by: ID of the participant that paid for the expense
  • split_between: IDs of the participants to split the expense between

Remove expense

Removes the specified expense from the bill.

URL: http://shareabill.com/bills/<SLUG>/expenses/<EXPENSE_ID>/remove/

Method(s): POST

Returns: HTTP 200, and JSON-encoded bill

Parameters: None

Settlements and payments

Add payment

Adds a payment to the specified bill.

URL: http://shareabill.com/bills/<SLUG>/payments/add/

Method(s): POST

Returns: HTTP 200, and JSON-encoded bill

Parameters:

  • amount: The amount that has been paid
  • paid_by: ID of the paying participant
  • paid_to: ID of the receiving participant

Remove payment

Removes a payment from the specified bill.

URL: http://shareabill.com/bills/<SLUG>/payments/<PAYMENT_ID>/remove/

Method(s): POST

Returns: HTTP 200, and JSON-encoded bill

Parameters: None