Home

BeansBooks API

Crowdsource your data entry, remove errors, reduce overhead and create real time analytics by connecting your e-commerce, point of sale and payroll systems to BeansBooks. BeansBooks extensive API enables automatic creation of customers, vendors, sales orders, purchase orders, invoices and more.

---

Setting up the API

All instances of BeansBooks are already setup to use the API—you simply need to generate an API key to get started. To do so, click the Setup tab at the top of your BeansBooks company, followed by Users. On that page you will find a button labeled Generate API Key. Once a key is generated, it is revealed only once—make sure you save it. If you lose your key, or you are unsure of the security of your key, you can simply generate a new one from this same page.

Above the API Key, you will find a URL to your API end-point. Make a note of this, as it is the base URL for all API requests to your instance of BeansBooks.

---

Authenticating a Request

At a minimum, all requests require the following parameters to be attached:

1. auth_uid (required) - The unique ID assigned to your API Key's user account.
2. auth_key (required) - The key itself.
3. auth_expiration (required) - A unique identifier to validate your current API Key.

---

Requests

All requests should contain a JSON-encoded data object in the POST body. In addition to the above parameters, you should include whatever is required for the specific action. As an example, performing a lookup on a customer invoice would have the following data sent to /api/Customer/Sale/Lookup:

{
  auth_uid: 4,
  auth_key: "abcdefghijklmnopqrstuvwxyz0123456789",
  auth_expiration: 98765,
  id: 1005
}

---

Responses

Responses are encoded in JSON and contain, at minimum, the following attributes (if applicable):

`. success BOOLEAN Whether or not the request was successful. If this is not true, either of the error fields will be populated appropriately.

1. config_error STRING Included if the BeansBooks instance is not yet setup.
2. auth_error STRING Included if the API Key information is incorrect or access is denied to a particular feature.
3. error STRING Included if the request failed due to bad request data or an internal error.
4. data OBJECT An object with the return data for the specific request.

As an example, the above request to /api/Customer/Sale/Lookup would return the following:

{
  "success":true,
  "error":"",
  "data":{
    "sale":{
      "id":"1005",
      "customer":{
        "id":"1",
        "first_name":"Test",
        "last_name":"Customer",
        "company_name":"",
        "email":"test@customer.beans",
        "phone_number":"",
        "fax_number":"",
        "default_billing_address_id":"1",
        "default_shipping_address_id":"1",
        "default_account":{
          "id":"15",
          "parent_account_id":"11",
          "name":"Credit Card Receivable",
          "code":"creditcardreceiv",
          "reconcilable":false,
          "terms":7,
          "balance":-8140,
          "deposit":false,
          "payment":false,
          "receivable":true,
          "payable":false,
          "writeoff":false,
          "type":{
            "id":"6",
            "name":"Accounts Receivable",
            "code":"accountsreceivable",
            "table_sign":"-1"
          }
        },
        "sales_count":3,
        "sales_total":10285,
        "balance_pending":-2145,
        "balance_pastdue":-8140
      },
      "account":{
        "id":"15",
        "parent_account_id":"11",
        "name":"Credit Card Receivable",
        "code":"creditcardreceiv",
        "reconcilable":false,
        "terms":7,
        "balance":-8140,
        "deposit":false,
        "payment":false,
        "receivable":true,
        "payable":false,
        "writeoff":false,
        "type":{
          "id":"6",
          "name":"Accounts Receivable",
          "code":"accountsreceivable",
          "table_sign":"-1"
        }
      },
      "sent":false,
      "refund_sale_id":null,
      "date_created":"2013-08-13",
      "date_billed":null,
      "date_due":null,
      "date_cancelled":null,
      "create_transaction_id":"12",
      "invoice_transaction_id":null,
      "cancel_transaction_id":null,
      "subtotal":"1950.00",
      "total":"1950.00",
      "taxestotal":0,
      "balance":"-1950.00",
      "sale_number":"S1005",
      "order_number":null,
      "po_number":"",
      "quote_number":"",
      "billing_address":{
        "id":"1",
        "customer_id":"1",
        "first_name":"Test",
        "last_name":"Customer",
        "company_name":"",
        "address1":"123 Test Street",
        "address2":"",
        "city":"Somewhere",
        "state":"Broken",
        "zip":"321456",
        "country":"US",
        "standard":"Test Customer 123 Test Street Somewhere, Broken 321456 US "
       },
      "shipping_address":{
        "id":"1",
        "customer_id":"1",
        "first_name":"Test",
        "last_name":"Customer",
        "company_name":"",
        "address1":"123 Test Street",
        "address2":"",
        "city":"Somewhere",
        "state":"Broken",
        "zip":"321456",
        "country":"US",
        "standard":"Test Customer 123 Test Street Somewhere, Broken 321456 US "
      },
      "lines":[
        {
          "id":"10",
          "account":{
            "id":"30",
            "parent_account_id":"3",
            "name":"Product Sales",
            "code":"productsales",
            "reconcilable":false,
            "terms":0,
            "balance":8140,
            "deposit":false,
            "payment":false,
            "receivable":false,
            "payable":false,
            "writeoff":true,
            "type":{
              "id":"11",
              "name":"Income",
              "code":"income",
              "table_sign":"1"
            }
          },
          "description":"One Product",
          "amount":"195.00",
          "quantity":"10",
          "total":"1950.00",
          "line_taxes":[]
        }
      ],
      "taxes":[],
      "payments":[],
      "status":"SO Not Sent",
      "title":"Sales Order S1005"
    }
  }
}