NAV Hiveage API Reference

Introduction

Hiveage provides access to your data via a JSON RESTful API, making it easy to create web and desktop applications that integrate with your account. With the API, you can access the following resource types. Visit each section to learn about the actions available for them.

Getting Started

Hiveage API is enabled to all user accounts by default. You can find your API key from Launchpad > Your Global Profile, and start issuing API requests right away! Your API login inherits the same permissions as your regular login, and you can certainly carry out nearly as much workload with it. However, to prevent API misuses, we have put forth several limits on the per hour API requests that can originate from the same user account. You can find more about these restrictions below.

If you find any features missing or have any suggestions, please contact us at [email protected].

Authentication

To authorize, use this code:

curl "api_endpoint_here"
  -u "6ZQHxidcLHnkcsnDbfM5"

Make sure to replace 6ZQHxidcLHnkcsnDbfM5 with your API key.

API access to the data under your user account(s) is protected by your API key. You can find your API key from Your Global Profile. If at anytime, you find the API key has become vulnerable, please regenerate the key using Regenerate button next to the API key.

Authentication to the Hiveage API is provided through HTTP Basic Authentication. Use your API key as the username and ignore the password when making requests. Please don’t use your regular account password with API requests.

Network

The Connection Object

EXAMPLE OBJECT

{ 
  "network": {
    "id": 1269,
    "hash_key": "Uv1xF6KVxj9GoA"
    "name": "Example Inc",
    "business_email": "[email protected]",
    "currency": "USD",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "address": "941 Example Ave. #5 ",
    "city": "Long Beach",
    "state_name": "CA",
    "zip_code": "90813",
    "country": "United States",
    "phone": "562-556-5555",
    "fax":"562-381-5555",
    "website_url": "http://example.hiveage.com",
    "created_at": "2010-07-18T00:08:10Z",
    "primary_contact_first_name": "John",
    "primary_contact_last_name": "Roe",
    "category": "organization",
    "language": "en-us"
  }
}

Each company, client, and vendor in Hiveage is a Connection, and together they make up the Network of that company. A connection could be an organization or an individual.

All other objects in Hiveage should be associated with at least one Connection.

Parameter Description
hash_key string
name string Returns name of organization connections only
first_name string Returns first_name of individual connections only
last_name string Returns first_name of individual connections only
business_email string
address string
category string There are two categories, organization and individual
country string
city string
state_name string
zip_code string
phone string
fax string
language string The default language is en-us. Other supported lanugages: en-uk, zh, da, nl, de, et, fil, fr, hi, it, ja, ko, ms, pt-br, ru, si, es.
currency string
currency_symbol string E.g. $, £,
currency_iso_code string E.g. USD, GPB, EUR
primary_contact_first_name string This is first name of the person assigned as the primary point of contact. If network is an individual, this values is network’s first_name
primary_contact_last_name string This is last name of the person assigned as the primary point of contact. If network is an individual, this values is network’s last_name

Create a new Connection

DEFINITION
POST https://[subdomain].hiveage.com/api/network

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/network \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -H "Accept: application/json" \
  -d network[business_email]="[email protected]" \
  -d network[first_name]="John" \
  -d network[last_name]="Doe" \
  ...
  -d network[category]="organization" \


EXAMPLE JSON REQUEST BODY
{ 
  "network": {
    "first_name": "John",
    "last_name": "Doe",
    "business_email": "[email protected]",
    "currency": "USD",
    "address": "941 Example Ave. #5 ",
    "city": "Long Beach",
    "state_name": "CA",
    "zip_code": "90813",
    "country": "United States",
    "phone": "562-556-5555",
    "fax":"562-381-5555",
    "website_url": "http://example.hiveage.com",
    "category": "organization",
    "language": "en-us",
    "primary_contact_first_name": "John",
    "primary_contact_last_name": "Roe",
    "custom_fields": [{name: "key", value: "val"}]
  }
}

You can create a new company, client or vendor by creating a new Connection.

Arguments

Parameter Description
name required If the network category is organization, returns the name of the organization
first_name required If the network category is individual, you must to set first_name and last_name. The name argument is used only for organization connections.
last_name optional
business_email required
language required The default language is en-us. Other supported lanugages: en-uk, zh, da, nl, de, et, fil, fr, hi, it, ja, ko, ms, pt-br, ru, si, es.
currency required
category required There are two categories, organization and individual
address optional
country optional
city optional
state_name optional
zip_code optional
phone optional
fax optional
primary_contact_first_name optional
primary_contact_last_name optional

Returns

Returns a connection object if the call is successful.

Retrieve a Connection

DEFINITION
GET https://[subdomain].hiveage.com/api/network/[hash_key]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key]
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{ 
  "network": {
    "id": 1269,
    "hash_key": "Uv1xF6KVxj9GoA"
    "first_name": "John",
    "last_name": "Doe",
    "business_email": "[email protected]",
    "currency": "USD",
    "address": "941 Example Ave. #5 ",
    "city": "Long Beach",
    "state_name": "CA",
    "zip_code": "90813",
    "country": "United States",
    "phone": "562-556-5555",
    "fax":"562-381-5555",
    "website_url": "http://example.hiveage.com",
    "category": "organization",
    "language": "en-us",
    "primary_contact_first_name": "John",
    "primary_contact_last_name": "Roe"
  }
}

This retrieves the details of an existing Connection. You need to supply only the hash_key that was returned.

Arguments

Parameter Description
hash_key required Network object hash_key.

Update a Connection

Updating an existing connection requires hash_key and other parameters. Returns the updated Connection.

DEFINITION
PUT https://[subdomain].hiveage.com/api/network/[hash_key]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d network[business_email]="[email protected]"

SAMPLE JSON RESPONSE
{
  "network": {
    "id": 1269,
    "hash_key": "Uv1xF6KVxj9GoA"
    "first_name": "John",
    "last_name": "Doe",
    "business_email": "[email protected]",
    "currency": "USD",
    "address": "941 Example Ave. #5 ",
    "city": "Long Beach",
    "state_name": "CA",
    "zip_code": "90813",
    "country": "United States",
    "phone": "562-556-5555",
    "fax":"562-381-5555",
    "website_url": "http://example.hiveage.com",
    "category": "individual",
    "language": "en-us"
  }
}

Arguments

Parameter Description
hash_key required
name required If the network category is organization, returns the name of the organization
first_name required If the network category is individual, you must to set first_name and last_name. The name argument is used only for organization connections.
last_name optional
business_email required
language required The default language is en-us. Other supported lanugages: en-uk, zh, da, nl, de, et, fil, fr, hi, it, ja, ko, ms, pt-br, ru, si, es.
currency required
category required There are two categories, organization and individual
address optional
country optional
city optional
state_name optional
zip_code optional
phone optional
fax optional

Returns

Returns a Connection object if the call is successful.

Delete a Connection

A deleted Connection is moved to the Trash. Once deleted, it is no longer possible to create new statements (invoices, estimates etc.) for that Connection.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/network/[hash_key]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{ 
  "network": {
    "deleted": true,
    "id": "Uv1xF6KVxj9GoA"
  }
}

Arguments

Parameter Description
hash_key required The hash_key of the connection to be deleted.

Returns an object with a deleted parameter on success.

List all Connections

Returns a list of your connections, sorted alphabetically.

DEFINITION
GET https://[subdomain].hiveage.com/api/network

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/network\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{ 
  "networks": [{
    "id": 1269,
    "hash_key": "Uv1xF6KVxj9GoA"
    "first_name": "John",
    "last_name": "Doe",
    "business_email": "[email protected]",
    "currency": "USD",
    "address": "941 Example Ave. #5 ",
    "city": "Long Beach",
    "state_name": "CA",
    "zip_code": "90813",
    "country": "United States",
    "phone": "562-556-5555",
    "fax":"562-381-5555",
    "website_url": "http://example.hiveage.com",
    "category": "individual",
    "language": "en-us"
  },
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in the set of results.
order optional The Connection list will be ordered by name, can be ordered by desc or asc. The defaul value is asc.

Invoice Activities

Returns a list of associated invoices, sorted by date and created_at.

DEFINITION
GET https://[subdomain].hiveage.com/api/network/[hash_key]/invoices

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key]/invoices\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "invoices": [{
    "id": 12,
    "connection": { 
      "id": 53321,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "hash_key": "bCbFYNj3RFM2uQ",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "total_due": "0.00",
    "paid_total": "0.00",
    "created_at": "2015-01-22T19:22:28Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in the set of results.

Estimate Activities

Returns a list of associated estimates, sorted by created_at.

DEFINITION
GET https://[subdomain].hiveage.com/api/network/[hash_key]/estimates

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key]/estimates\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "estimates": [{
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "date": "2015-01-18",
    "expire_date": "2016-01-18"
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Estimate Summary",
    "note": "Estimate Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "created_at": "2015-01-22T19:22:28Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in the set of results.

Recurring Invoice Activities

Returns a list of associated recurring invoices, sorted by created_at.

DEFINITION
GET https://[subdomain].hiveage.com/api/network/[hash_key]/recurring_invoices

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key]/recurring_invoices\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{ 
  "recurring_invoices": [{
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "recurring_method": "save_draft", 
    "next_billing_date": "2015-10-18",
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "iteration_no": 0,
    "due_date_options": 15,
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "created_at": "2015-01-22T19:22:28Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in the set of results.

Contacts

One or many contacts can be associated with a connection object. The API allows you to create, update and delete contacts. Contact details are required when you send statements (invoices, estimates etc.).

The Contact Object

EXAMPLE OBJECT

{
  "contact": {
    "first_name": "Peter",
    "last_name": "Pan",
    "email": "[email protected]",
    "mobile": "562-556-5555",
    "phone": "562-381-5555",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Attribute Description
id integer Contact ID
first_name string Contact first name used in email delivery. Eg: Peter
last_name string
email string Email used for delivering statements. Eg: Peter Pan <[email protected]>
mobile string
phone string

Create a New Contact

DEFINITION
POST https://[subdomain].hiveage.com/api/network/[hash_key]/contacts

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key]/contacts\
  -H "Accept: application/json" \
  -d 6ZQHxidcLHnkcsnDbfM5: \
  -d contact[first_name]="Peter" \
  -d contact[last_name]="Pan" \
  -d contact[email]="[email protected]" \
  -d contact[mobile]="562-556-5555" \
  -d contact[phone]="562-381-5555" \


EXAMPLE RESPONSE
{
  "contact": {
    "id": 159883,
    "first_name": "Peter",
    "last_name": "Pan",
    "email": "[email protected]",
    "mobile": "562-556-5555",
    "phone": "562-381-5555",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

You can create contacts associated with a connection object. The connection hash_key must be specified in the request URL.

Arguments

Parameter Description
first_name required First name (required) to be used in email delivery. Eg: Peter
last_name optional
email required Email (required) to be used in email delivery. Eg: Peter Pan <[email protected]>
Contact email addresses available for BCC field.
mobile optional
phone optional

Return

Returns the contact object associted with a connection.

Retrieve a Contact

Retrieve a contact object given ID.

DEFINITION
GET https://[subdomain].hiveage.com/api/network/[hash_key]/contacts/[id]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key]/contacts/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{
  "contact": {
    "id": 1245,
    "first_name": "Peter",
    "last_name": "Pan",
    "email": "[email protected]",
    "mobile": "562-556-5555",
    "phone": "562-381-5555",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Parameter Description
id required The ID of the Contact object.
NOTE: The associated connection hash_key must be specified first.

Returns

Returns a contact JSON object if a valid contact ID was provided. Returns an error otherwise.

Update a Contact

Update a contact associated with a connection.

DEFINITION
PUT https://[subdomain].hiveage.com/api/network/[hash_key]/contacts/[id]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key]/contacts/[id] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d contact[first_name]="Peter" \
  -d contact[email]="[email protected]" \

EXAMPLE RESPONSE
{ 
  "contact": {
    "id": 1245,
    "first_name": "Peter",
    "last_name": "Pan",
    "email": "[email protected]",
    "mobile": "562-556-5555",
    "phone": "562-381-5555",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Parameter Description
first_name required First name (required) to be used in email delivery. Eg: Peter
last_name optional
email required Email (required) to be used in email delivery. Eg: Peter Pan <[email protected]>
Contact email addresses available for BCC field.
mobile optional
phone optional

Returns

Returns a updated contact JSON object if a valid contact ID was provided. Returns an error otherwise.

Delete a Contact

Deleting a contact object permanently.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/network/[hash_key]/contacts/[id]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key]/contacts/[id] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "contact": {
    "deleted": true,
    "id": "1234505"
  }
}

Arguments

Parameter Description
id required The ID of the contact to be deleted.

Returns an object with a deleted parameter on success.

List All contacts

Returns a list of contacts. The contacts are returned sorted alphabetically.

DEFINITION
GET https://[subdomain].hiveage.com/api/network/[hash_key]/contacts

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/network/[hash_key]/contacts \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "contacts": [{
    "id": 1245,
    "first_name": "Peter",
    "last_name": "Pan",
    "email": "[email protected]",
    "mobile": "562-556-5555",
    "phone": "562-381-5555",
    "created_at": "2014-07-21T11:04:58Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in the results et
order optional The list has been ordered by first_name. So you can order by desc or asc. The defaul value is asc.

Invoices

The Invoice Object

NOTE: This is a sample invoice object with Taxes, Discounts and Shipping charges added to the invoice subtotal.

EXAMPLE OBJECT

{
  "invoice": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "total_due": "0.00",
    "paid_total": "0.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [{
      "id": 3,
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts": [{
      "id": 4,
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts": [{
      "id": 5,
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items": [{
      "id": 245,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "total": "100.00",
      "sort_order": 1,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "expenses": [{
      "id": 246,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "total": "100.00",
      "sort_order": 2,
      "created_at": "2015-01-22T19:22:28Z"
    },{...}],

    "tasks": [{
      "id": 300,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 3,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "trips": [{
      "id": 340,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 4,
      "created_at": "2015-01-22T19:22:28Z"
    }]
  }
}

Attributes

Attribute Description
id integer Item ID
connection hash Client details specified by id and name.
date string
due_date string
hash_key string
state string An invoice can have different states: draft, viewed, sent, paid, partial
summary string
note string
company_id string Owner’s Hiveage account id
statement_no string statement_no is uniqe. Eg: IN-001
payment_options array Associated payment method keys in an array. Payment method keys: ["cash", "check", "bank_transfer", "paypal"]
allow_partial_payments boolean
send_receipts_automatically boolean
send_reminders boolean
po_number string
currency_iso_code string
currency_symbol string
billed_total string
formatted_billed_total string
sub_total string
formatted_sub_total string
total_due string
formatted_total_due
paid_total string
formatted_paid_total string

Adding Tax, Discount and Shipping into invoice

Taxes, discounts and shipping charges can be added to the invoice sub total or line items (items, expenses, mileages and tasks).

Tax

Attributes

Attribute Description
id integer
name string Tax name
key integer Saved tax reference id
combined_amount_percent string Fixed or percentage value. Eg: 5.00 or 5.25%
percentage boolean If the tax amount is a precentage, this value should be true, if not by default false.

Discount

Attributes

Attribute Description
id integer
name string Discount name
key integer Saved discount reference id
combined_amount_percent string Fixed or percentage value. Eg: 5.00 or 5.25%
percentage boolean If the discount amount is a precentage, this value should be true, if not by default false.

Shipping Amount

Attributes

Attribute Description
id integer
name string Shipping amount name
key integer Saved shipping amount reference id
combined_amount_percent string Fixed or percentage value. Eg: 5.00 or 5.25%`
percentage boolean If the shipping amount is a precentage, this value should be true, if not by default false.

Create a New Invoice

DEFINITION
POST https://[subdomain].hiveage.com/api/invs

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d invoice[summary]="Invoice summary" \
  -d invoice[date]="2014-01-20" \
  -d invoice[connection_id]="14578" \
  ...
  -d invoice[note]="Invoice note"

EXAMPLE JSON REQUEST BODY
{ 
  "invoice": {
    "connection_id": 14578,
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": 1,
    "send_receipts_automatically": 1,
    "po_number": "PO-number",
    "send_reminders": false,

    "taxes_attributes": [{
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts_attributes": [{
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts_attributes": [{
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "sort_order": 1
    }, {...}],

    "expenses_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "sort_order": 2
    },{...}],

    "tasks_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "sort_order": 3
    }, {...}],

    "trips_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "sort_order": 4
    }]
  }
}

Attributes

Parameter Description
connection_id required connection_id as specified in the Network section. It may be an individual connection id or organization id
date required Invoice date
due_date required Invoice due date
summary optional
note optional
statement_no required Invoice statement_no should be unique
payment_options optional Associated payment method keys in an array. Payment method keys: ["cash", "check", "bank_transfer", "paypal"]
allow_partial_payments optional
send_receipts_automatically optional
send_reminders optional
po_number optional

NOTE: Different types of line items (“Items”, “Expenses”, “Trips” and “Tasks”) can be added as shown in the example JSON request. Taxes, Discounts and Shipping charges could be added to invoice sub total or line items.

Retrieve an Invoice

Retrieve an invoice object with a specified hash_key.

DEFINITION
GET https://[subdomain].hiveage.com/api/invs/[hash_key]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{ 
  "invoice": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "hash_key": "bCbFYNj3RFM2uQ",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "total_due": "0.00",
    "paid_total": "0.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [{
      "id": 3,
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts": [{
      "id": 4,
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts": [{
      "id": 5,
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items": [{
      "id": 245,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "total": "100.00",
      "sort_order": 1,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "expenses": [{
      "id": 246,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "total": "100.00",
      "sort_order": 2,
      "created_at": "2015-01-22T19:22:28Z"
    },{...}],

    "tasks": [{
      "id": 300,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 3,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "trips": [{
      "id": 340,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 4,
      "created_at": "2015-01-22T19:22:28Z"
    }]
  }
}

Arguments

Parameter Description
hash_key required The hash_key of the invoice object.

Returns

Returns an invoice JSON object if a valid invoice hash_key was provided. Returns an error otherwise.

Update an Invoice

Update an invoice object.

DEFINITION
PUT https://[subdomain].hiveage.com/api/invs/[hash_key]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d invoice[statement_no]="IN-002" \
  -d invoice[summary]="Invoice summary to be updated" \
  -d invoice[connection_id]="53321" \

EXAMPLE RESPONSE
{
  "invoice": {
    "id": 12,
    "connection": { 
      "id": 53321,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "hash_key": "bCbFYNj3RFM2uQ",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "total_due": "0.00",
    "paid_total": "0.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [ {...}],
    "discounts": [{...}],
    "shipping_amounts": [{...}],

    "items": [{...}],
    "expenses": [{...}],
    "tasks": [{...}],
    "trips": [{...}]
  }
}

Attributes

Parameter Description
connection_id required connection_id as specified in the Network section. It may be your individual connection id or organization id
date required Invoice date
due_date required Invoice due date
summary optional
note optional
statement_no required Invoice statement_no should be unique
payment_options optional Associated payment method keys in an array. Payment method keys: ["cash", "check", "bank_transfer", "paypal"]
allow_partial_payments optional
send_receipts_automatically optional
send_reminders optional
po_number optional

Delete an Invoice

Deleting an invoice object will move it to Trash. It will not be deleted permanently. To permanently delete an invoice, the user has to log into Hiveage and delete it manually from the trash.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/invs/[hash_key]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "invoice": {
    "deleted": true,
    "id": "bCbFYNj3RFM2uQ"
  }
}

Arguments

Parameter Description
id required The hash_key of the invoice to be deleted.

Returns an object with a deleted parameter on success.

List All Invoices

Returns a list of invoices. The invoices are returned sorted alphabetically.

DEFINITION
GET https://[subdomain].hiveage.com/api/invs

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/invs\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "invoices": [{
    "id": 12,
    "connection": { 
      "id": 53321,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "hash_key": "bCbFYNj3RFM2uQ",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "total_due": "0.00",
    "paid_total": "0.00",
    "created_at": "2015-01-22T19:22:28Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in the results set
order optional The list is sorted by date, statement_no, state, and can ordered by desc or asc. The defaul value is asc.

Send Invoice

There are two ways to deliver a message.

i. Delivers an exisiting invoice without specifying any parameters. It will use defalut invoice email template values.

DEFINITION
POST https://[subdomain].hiveage.com/api/invs/[hash_key]/deliver

EXAMPLE REQUEST (i)
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key]/deliver\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \


EXAMPLE REQUEST (ii)
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key]/deliver\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d delivery[recipients]="[{name: 'Peter', email: '[email protected]'}, {name: 'Sam', email: '[email protected]'}]" \
  -d delivery[blind_copies]="[{name: 'Jane', email: '[email protected]'}]" \
  -d delivery[subject]="Message subject" \
  -d delivery[message]="Message content" \
  -d delivery[attachment]="true" \

SAMPLE JSON RESPONSE
{
  "send": "ok",
}

ii. To send a custom email message for an invoice, the following parameters could be set.

Arguments

Parameter Description
recipients required Specifies TO addresses of the invoice email. Eg: [{name: 'Peter', email: '[email protected]'}, {name: 'Sam', email: '[email protected]'}]
blind_copies required Specifies BCC addresses of the invoice email. Eg: [{name: 'Jane', email: '[email protected]'}]
subject required The subject of the invoice email
message required
attachment optional If the invoice PDF should be attached, this must be set to true; otherwise false by default.

Send Invoice Reminder

There are two ways to send an invoice reminder.

i. Delivers an exisiting invoice without specifying any parameters. It will use defalut invoice reminder template values.

DEFINITION
POST https://[subdomain].hiveage.com/api/invs/[hash_key]/reminder

EXAMPLE REQUEST (i)
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key]/reminder\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \


EXAMPLE REQUEST (ii)
$ curl https://[subdomain].hiveage.com/api/invs/[hash_key]/reminder\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d delivery[recipients]="[{name: 'Peter', email: '[email protected]'}, {name: 'Sam', email: '[email protected]'}]" \
  -d delivery[blind_copies]="[{name: 'Jane', email: '[email protected]'}]" \
  -d delivery[subject]="Message subject" \
  -d delivery[message]="Message content" \
  -d delivery[attachment]="true" \

SAMPLE JSON RESPONSE
{
  "send": "ok",
}

ii. You can set all parameters if you wish to send custom emali message to selected invoice.

Arguments

Parameter Description
recipients required Specifies TO addresses of the reminder email. Eg: [{name: 'Peter', email: '[email protected]'}, {name: 'Sam', email: '[email protected]'}]
blind_copies required Specifies BCC addresses of the reminder email. Eg: [{name: 'Jane', email: '[email protected]'}]
subject required The subject of the reminder email
message required
attachment optional If the invoice PDF should be attached, this must be set to true; otherwise false by default.

Estimates

The Estimate Object

NOTE: This is a sample estimate object with Taxes, Discounts and Shipping charges added to the estimate subtotal.

EXAMPLE OBJECT

{
  "estimate": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "date": "2015-01-18",
    "expire_date": "2016-01-18"
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Estimate summary",
    "note": "Estimate Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [{
      "id": 3,
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts": [{
      "id": 4,
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts": [{
      "id": 5,
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items": [{
      "id": 245,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "total": "100.00",
      "sort_order": 1,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "expenses": [{
      "id": 246,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "total": "100.00",
      "sort_order": 2,
      "created_at": "2015-01-22T19:22:28Z"
    },{...}],

    "tasks": [{
      "id": 300,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 3,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "trips": [{
      "id": 340,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 4,
      "created_at": "2015-01-22T19:22:28Z"
    }]
  }
}

Attributes

Attribute Description
id integer Estimate ID
connection hash Client details shown by id and name.
date string
expire_date string
hash_key string
state string An estimate can have different states: draft, viewed, sent, accept
summary string
note string
company_id string Owner’s Hiveage account id
statement_no string statement_no is uniqe string. Eg: IN-001
send_reminders boolean
currency_iso_code string
currency_symbol string
billed_total string
formatted_billed_total string
sub_total string
formatted_sub_total string

Adding Tax, Discount and Shipping into Estimate

You can add taxes, discounts and shipping charges into the estimate sub total or line items.

Tax

Attributes

Attribute Description
id integer
name string Tax name
key integer Saved tax reference id
combined_amount_percent string Fixed or percentage value. Eg: 5.00 or 5.25%
percentage boolean If the tax amount is a precentage, this value should be true, if not by default false.

Discount

Attributes

Attribute Description
id integer
name string Discount name
key integer Saved discount reference id
combined_amount_percent string Fixed or percentage value. Eg: 5.00 or 5.25%
percentage boolean If the discount is a precentage, this value should be true, if not by default false.

Shipping Amount

Attributes

Attribute Description
id integer
name string Shipping amount name
key integer Saved shipping amount reference id
combined_amount_percent string Fixed or percentage value. Eg: 5.00 or 5.25%
percentage boolean If the shipping charge is a precentage, this value should be true, if not by default false.

Create a New Estimate

DEFINITION
POST https://[subdomain].hiveage.com/api/estm

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/estm\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d estimate[summary]="Estimate summary" \
  -d estimate[date]="2014-01-20" \
  -d estimate[expire_date]="2016-01-07"
  -d estimate[connection_id]="14578" \
  ...
  -d estimate[note]="Estimate note"

EXAMPLE JSON REQUEST BODY
{ 
  "estimate": {
    "connection_id": 14578,
    "expire_date": "2016-10-01",
    "date": "2015-01-18",
    "summary": "Estimate summary",
    "note": "Estimate Note",
    "statement_no": "EST-001",
    "send_reminders": false,

    "taxes_attributes": [{
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts_attributes": [{
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts_attributes": [{
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "sort_order": 1
    }, {...}],

    "expenses_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "sort_order": 2
    },{...}],

    "tasks_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "sort_order": 3
    }, {...}],

    "trips_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "sort_order": 4
    }]
  }
}

Attributes

Parameter Description
connection_id required connection_id as specified in the Network section. It may be your individual connection id or organization id
date required Estimate date
due_date required Estimate expiration date
summary optional
note optional
statement_no required Estimate statement_no should be unique
send_reminders optional

NOTE: Different types of line items (“Items”, “Expenses”, “Trips” and “Tasks”) can be added as shown in the example JSON request. Taxes, Discounts and Shipping charges could be added to estimate sub total or line items.

Retrieve an Estimate

Retrieve an estimate object with a specified hash_key.

DEFINITION
GET https://[subdomain].hiveage.com/api/estm/[hash_key]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/estm/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{
  "estimate": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "date": "2015-01-18",
    "expire_date": "2016-01-18"
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Estimate Summary",
    "note": "Estimate Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [{
      "id": 3,
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts": [{
      "id": 4,
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts": [{
      "id": 5,
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items": [{
      "id": 245,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "total": "100.00",
      "sort_order": 1,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "expenses": [{
      "id": 246,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "total": "100.00",
      "sort_order": 2,
      "created_at": "2015-01-22T19:22:28Z"
    },{...}],

    "tasks": [{
      "id": 300,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 3,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "trips": [{
      "id": 340,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 4,
      "created_at": "2015-01-22T19:22:28Z"
    }]
  }
}

Returns

Returns a estimate JSON object if a valid estimate hash_key was provided. Returns an error otherwise.

Update an Estimate

Updating an estimate object.

DEFINITION
PUT https://[subdomain].hiveage.com/api/estm/[hash_key]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/estm/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d estimate[statement_no]="EST-002" \
  -d estimate[summary]="Estimate summary to be updated" \
  -d estimate[connection_id]="53321" \

EXAMPLE RESPONSE
{
  "estimate": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "date": "2015-01-18",
    "expire_date": "2016-01-18"
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Estimate Summary",
    "note": "Estimate Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [ {...}],
    "discounts": [{...}],
    "shipping_amounts": [{...}],

    "items": [{...}],
    "expenses": [{...}],
    "tasks": [{...}],
    "trips": [{...}]
  }
}

Attributes

Parameter Description
connection_id required connection_id as specified in the Network section. It may be your individual connection id or organization id
date required Estimate date
due_date required Estimate expiration date
summary optional
note optional
statement_no required Estimate statement_no should be unique
send_reminders optional

Delete an Estimate

Deleting an estimate object will move it to Trash. It will not be deleted permanently. To permanently delete an estimate, the user has to log into Hiveage and delete it manually from the trash.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/estm/[hash_key]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/estm/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "estimate": {
    "deleted": true,
    "id": "bCbFYNj3RFM2uQ"
  }
}

Arguments

Parameter Description
id required The hash_key of the estimate to be deleted.

Returns an object with a deleted parameter on success.

List All Estimates

Returns a list of estimates. The estimates are returned sorted alphabetically.

DEFINITION
GET https://[subdomain].hiveage.com/api/estm

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/estm\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "estimates": [{
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "date": "2015-01-18",
    "expire_date": "2016-01-18"
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Estimate Summary",
    "note": "Estimate Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "created_at": "2015-01-22T19:22:28Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in the results set
order optional The list is ordered by date, statement_no, state, and can be ordered by desc or asc. The defaul value is asc.

Send Estimate

There are two ways to deliver a message.

i. Delivers an exisiting estimate without specifying any parameters. It will use defalut estimate email template values.

DEFINITION
POST https://[subdomain].hiveage.com/api/estm/[hash_key]/deliver

EXAMPLE REQUEST (i)
$ curl https://[subdomain].hiveage.com/api/estm/[hash_key]/deliver\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \


EXAMPLE REQUEST (ii)
$ curl https://[subdomain].hiveage.com/api/estm/[hash_key]/deliver\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d delivery[recipients]="[{name: 'Peter', email: '[email protected]'}, {name: 'Sam', email: '[email protected]'}]" \
  -d delivery[blind_copies]="[{name: 'Jane', email: '[email protected]'}]" \
  -d delivery[subject]="Message subject" \
  -d delivery[message]="Message content" \
  -d delivery[attachment]="true" \

SAMPLE JSON RESPONSE
{
  "send": "ok",
}

ii. To send a custom email message for an estimate, the following parameters could be set.

Arguments

Parameter Description
recipients required Specifies TO addresses of the estimate email. Eg: [{name: 'Peter', email: '[email protected]'}, {name: 'Sam', email: '[email protected]'}]
blind_copies required Specifies BCC addresses of the estimate email. Eg: [{name: 'Jane', email: '[email protected]'}]
subject required The subject of the estimate email
message required
attachment optional If the estimate PDF should be attached, this must be set to true; otherwise false by default.

Recurring Invoices

The Recurring Invoice Object

NOTE: This is a sample recurring invoice object with Taxes, Discounts and Shipping charges added to the invoice subtotal.

EXAMPLE OBJECT

{
  "recurring_invoie": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "recurring_method": "save_draft", 
    "next_billing_date": "2015-10-18",
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "iteration_no": 2,
    "due_date_options": 15,
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [{
      "id": 3,
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts": [{
      "id": 4,
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts": [{
      "id": 5,
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items": [{
      "id": 245,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "total": "100.00",
      "sort_order": 1,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "expenses": [{
      "id": 246,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "total": "100.00",
      "sort_order": 2,
      "created_at": "2015-01-22T19:22:28Z"
    },{...}],

    "tasks": [{
      "id": 300,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 3,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "trips": [{
      "id": 340,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 4,
      "created_at": "2015-01-22T19:22:28Z"
    }]
  }
}

Attributes

Attribute Description
id integer Item ID
connection hash Client details shown by id and name.
recurring_method string There are three recurring methods: save_draft, auto_send, auto_bill.
start_date string The date to generate the first invoice when this recurring profile is started.
next_billing_date string The date to generate the next invoice from this recurring profile.
profile_name string Profile name is required to indentify the recurring profile.
profile_no string The Profile ID will be used to create a separate invoice number sequence for this recurring invoice profile. If you leave this field blank, each invoice generated by this recurring profile will be assigned the next available number on your main invoice number sequence.
occurrences integer Enter number of occurrences to repeat. You may enter 0 to repeat forever.
interval_unit string There are four type of intervals available: days, weeks, months, years
interval integer Number of interval units
due_date_options integer Number of days the invoice should be due in, after being generated by the recurring profile.
hash_key string
state string Invoice has different type of states: draft, scheduled, pending, active, completed, closed.
summary string
note string
company_id string Owner’s Hiveage account id
payment_options array Associated payment method keys in an array. Payment method keys: ["cach", "check", "bank_transfer", "paypal"]
allow_partial_payments boolean
send_receipts_automatically boolean
send_reminders boolean
po_number string
currency_iso_code string
currency_symbol string
billed_total string
formatted_billed_total string
sub_total string
formatted_sub_total string

Adding Tax, Discount and Shipping into invoice

Taxes, discounts and shipping charges can be added to the invoice sub total or line items (items, expenses, mileages and tasks).

Tax

Attributes

Attribute Description
id integer
name string Tax name
key integer Saved tax reference id
combined_amount_percent string Fixed or percentage value. Eg: 5.00 or 5.25%
percentage boolean If the tax amount is a precentage, this value should be true, if not by default false.

Discount

Attributes

Attribute Description
id integer
name string Discount name
key integer Saved discount reference id
combined_amount_percent string Fixed or percentage value. Eg: 5.00 or 5.25%
percentage boolean If the discount amount is a precentage, this value should be true, if not by default false.

Shipping Amount

Attributes

Attribute Description
id integer
name string Shipping amount name
key integer Saved shipping amount reference id
combined_amount_percent string Fixed or percentage value. Eg: 5.00 or 5.25%`
percentage boolean If the shipping amount is a precentage, this value should be true, if not by default false.

Create a New Recurring Invoice

DEFINITION
POST https://[subdomain].hiveage.com/api/rinv/

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/rinv/ \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d recurring_invoice[summary]="Invoice summary"\
  -d recurring_invoice[connection_id]="14578"\
  -d recurring_invoice[recurring_method]="save_draft"\
  -d recurring_invoice[start_date]="2015-02-30"\
  -d recurring_invoice[profile_name]="RP-bill"\
  -d recurring_invoice[occurrences]=5\
  -d recurring_invoice[interval_unit]="years"\
  -d recurring_invoice[interval]=4\
  ...
  -d recurring_invoice[note]="Invoice note"

EXAMPLE JSON REQUEST BODY
{
  "recurring_invoice": {
    "connection_id": 14578,
    "recurring_method": "save_draft", 
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "due_date_options": 15,
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "send_reminders": false,

    "taxes_attributes": [{
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts_attributes": [{
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts_attributes": [{
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "sort_order": 1
    }, {...}],

    "expenses_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "sort_order": 2
    },{...}],

    "tasks_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "sort_order": 3
    }, {...}],

    "trips_attributes": [{
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "sort_order": 4
    }]
  }
}

Attributes

Parameter Description
connection_id required connection_id as specified in the Network section. It may be an individual connection id or organization id.
recurring_method string There are three recurring methods: save_draft, auto_send, auto_bill.
start_date string The date to generate the first invoice when this recurring profile is started. This cannot be updated after the first invoice is generated.
profile_name string Profile name is required to indentify after save into the list.
profile_no string The Profile ID will be used to create a separate invoice number sequence for this recurring invoicing schedule. If you leave this field blank, each invoice generated by this recurring schedule will be assigned the next available number on your main invoice number sequence.
occurrences integer Enter number of occurrences to repeat. You may enter 0 to repeat forever.
interval_unit string There are four type of intervals available: days, weeks, months, years
interval integer Number of interval units
due_date_options integer Number of days the invoice should be due in, after being generated by the recurring profile.
summary optional
note optional
payment_options optional Associated payment method keys in an array. Payment method keys: [“cach”, “check”, “bank_transfer”, “paypal”]
allow_partial_payments optional
send_receipts_automatically optional
send_reminders optional
po_number optional

NOTE: Different types of line items (“Items”, “Expenses”, “Trips” and “Tasks”) can be added as shown in the example JSON request. Taxes, Discounts and Shipping charges could be added to invoice sub total or line items.

Retrieve a Recurring Invoice

Retrieve a recurring invoice object with a specified hash_key.

DEFINITION
GET https://[subdomain].hiveage.com/api/rinv/[hash_key]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/rinv/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{ 
  "recurring_invoice": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "recurring_method": "save_draft", 
    "next_billing_date": "2015-10-18",
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "iteration_no": 0,
    "due_date_options": 15,
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [{
      "id": 3,
      "name": "VAT",
      "key": 23,
      "combined_amount_percent": "5%",
      "percentage": true
    }, {...}],

    "discounts": [{
      "id": 4,
      "name": "DIS",
      "key": 145,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "shipping_amounts": [{
      "id": 5,
      "name": "DHL",
      "key": 205,
      "combined_amount_percent": "5",
      "percentage": false
    }, {...}],

    "items": [{
      "id": 245,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "price": "10.00",
      "quantity": "10",
      "unit": "hourly",
      "total": "100.00",
      "sort_order": 1,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "expenses": [{
      "id": 246,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "amount": "10.00",
      "total": "100.00",
      "sort_order": 2,
      "created_at": "2015-01-22T19:22:28Z"
    },{...}],

    "tasks": [{
      "id": 300,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "duration": "120",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 3,
      "created_at": "2015-01-22T19:22:28Z"
    }, {...}],

    "trips": [{
      "id": 340,
      "date": "2015-10-18",
      "description": "Item descriptions",
      "distance": "2",
      "rate": "10.00",
      "total": "20.00",
      "sort_order": 4,
      "created_at": "2015-01-22T19:22:28Z"
    }]
  }
}

Arguments

Parameter Description
hash_key required The hash_key of recurring invoice object.

Returns

Returns a recurring invoice JSON object if a valid hash_key was provided. Returns an error otherwise.

Update a Recurring Invoice

Update a recurring invoice object.

DEFINITION
PUT https://[subdomain].hiveage.com/api/rinv/[hash_key]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/rinv/[hash_key] \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d recurring_invoice[summary]="Invoice summary"\
  -d recurring_invoice[connection_id]="14578"\
  -d recurring_invoice[recurring_method]="save_draft"\
  -d recurring_invoice[next_billing_date]="2015-02-30"\
  -d recurring_invoice[occurrences]=5\
  -d recurring_invoice[interval]="1"\
  -d recurring_invoice[interval_unit]="years"\
  ...
  -d recurring_invoice[note]="Invoice note"

EXAMPLE RESPONSE
{
  "recurring_invoice": {
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "recurring_method": "save_draft", 
    "next_billing_date": "2015-10-18",
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "iteration_no": 0,
    "due_date_options": 15,
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "created_at": "2015-01-22T19:22:28Z",

    "taxes": [ {...}],
    "discounts": [{...}],
    "shipping_amounts": [{...}],

    "items": [{...}],
    "expenses": [{...}],
    "tasks": [{...}],
    "trips": [{...}]
  }
}

Attributes

Parameter Description
connection_id required as specified in the Network section. It may be an individual connection ID or organization ID
recurring_method string There are three recurring methods: save_draft, auto_send, auto_bill.
next_billing_date string The date to generate the next invoice from this recurring profile once its active.
profile_name string Profile name is required to indentify the recurring profile.
profile_no string The Profile ID will be used to create a separate invoice number sequence for this recurring invoicing schedule. If you leave this field blank, each invoice generated by this recurring schedule will be assigned the next available number on your main invoice number sequence.
occurrences integer Enter number of occurrences to repeat. You may enter 0 to repeat forever.
interval_unit string There are four type of intervals available: days, weeks, months, years
interval integer Number of interval units
due_date_options integer Number of days the invoice should be due in, after being generated by the recurring profile.
summary optional
note optional
payment_options optional Associated payment method keys in an array. Payment method keys: ["cach", "check", "bank_transfer", "paypal"]
allow_partial_payments optional
send_receipts_automatically optional
send_reminders optional
po_number optional

Delete a Recurring Invoice

Deleting an recurring invoice object will move it to Trash. It will not be deleted permanently. To permanently delete a recurring invoice, the user has to log into Hiveage and delete it manually from the trash.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/rinv/[hash_key]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/rinv/[hash_key]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "recurring_invoice": {
    "deleted": true,
    "id": "bCbFYNj3RFM2uQ"
  }
}

Arguments

Parameter Description
id required The hash_key of the invoice to be deleted.

Returns an object with a deleted parameter on success.

List All Recurring Invoices

Returns a list of recurring invoices. The invoices are returned sorted alphabetically.

DEFINITION
GET https://[subdomain].hiveage.com/api/rinv

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/rinv\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{ 
  "recurring_invoices": [{
    "id": 12,
    "connection": { 
      "id": 12878,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "recurring_method": "save_draft", 
    "next_billing_date": "2015-10-18",
    "start_date": "2015-01-18",
    "profile_name": "RI-bill",
    "profile_no": "MAC",
    "occurrences": 5,
    "interval": 1,
    "interval_unit": "years",
    "iteration_no": 0,
    "due_date_options": 15,
    "hash_key": "q00MYh2dywH6RA",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "created_at": "2015-01-22T19:22:28Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in results set
order optional The list has been ordered by profile_name, next_billing_date, state, interval_unit and created_at, and can be ordered by desc or asc. The defaul value is asc.

Invoice Activities

Returns a list of generated invoices for one particular recurring invoice. The invoices are returned sorted created_at date.

DEFINITION
GET https://[subdomain].hiveage.com/api/rinv/q00MYh2dywH6RA/invoices

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/rinv/q00MYh2dywH6RA/invoices\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "invoices": [{
    "id": 12,
    "connection": { 
      "id": 53321,
      "hash_key": "qavTJeHbZItwcg",
      "name": "Peter"
     },
    "due_date": "2015-10-18",
    "date": "2015-01-18",
    "hash_key": "bCbFYNj3RFM2uQ",
    "state": "draft",
    "summary": "Invoice summary",
    "note": "Invoice Note",
    "company_id": 2459,
    "statement_no": "IN-001",
    "payment_options": ["paypal", "cash", "check"],
    "allow_partial_payments": true,
    "send_receipts_automatically": true,
    "po_number": "PO-number",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "send_reminders": false,
    "billed_total": "100.00",
    "sub_total": "100.00",
    "total_due": "0.00",
    "paid_total": "0.00",
    "created_at": "2015-01-22T19:22:28Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in results set
order optional The list has been ordered by created_at.

Invoice Payments

Hiveage allows you to enter payments for invoices.

The Payment Object

EXAMPLE OBJECT

{
  "payment": {
    "id": 2234,
    "date": "2015-01-20",
    "amount": "10.0",
    "formatted_amount": "$10.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Attribute Description
id integer Payment ID
date string Date the payment was received.
amount string Payment amount
formatted_balance string
balance string
formatted_balance string
payment_method string The following payment methods are supported: cash, check, other, bank_transfer, google_wallet, wepay, twocheckout, paypal, paypal_pro, braintree, authorizenet and stripe.
details string Payment details
combined_payment_details string payment_method and details values combined
currency_iso_code string
currency_symbol string
payment_receipt_no string Payment receipt number
payment_receipt_hash_key string Payment hash key.
state string For offline payments (e.g. bank transfers), whether the payment is realized or unrealized.
created_at string

Create a New Payment

DEFINITION
POST https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d payment[amount]="10" \
  -d payment[payment_method]="paypal" \
  -d payment[date]="2015-01-25" \
  -d payment[details]="Payment description" \


EXAMPLE RESPONSE
{
  "payment": {
    "id": 2235,
    "date": "2015-01-20",
    "amount": "10.0",
    "formatted_amount": "$10.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Parameter Description
date string Date the payment was received.
amount string Payment amount
payment_method string The following payment methods are supported: cash, check, other, bank_transfer, google_wallet, wepay, twocheckout, paypal, paypal_pro, braintree, authorizenet and stripe.
details string Payment details

Return

Returns the invoice payment object.

Retrieve a Payment

Retrieve a payment with a specified ID.

DEFINITION
GET https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{
  "payment": {
    "id": 10,
    "date": "2015-01-20",
    "amount": "10.0",
    "formatted_amount": "$10.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Returns

Returns a payment JSON object if a valid payment id was provided. Returns an error otherwise.

Update a Payment

DEFINITION
PUT https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10 \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d payment[amount]="5" \

EXAMPLE RESPONSE
{
  "payment": {
    "id": 10,
    "date": "2015-01-20",
    "amount": "5.0",
    "formatted_amount": "$5.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Parameter Description
date string Date the payment was received.
amount string Payment amount
payment_method string The following payment methods are supported: cash, check, other, bank_transfer, google_wallet, wepay, twocheckout, paypal, paypal_pro, braintree, authorizenet and stripe.
details string Payment details

Delete a Payment

Deletes a payments object permanently.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/10\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "deleted": true,
  "id": "10"
}

Returns an object with a deleted parameter on success.

List All Payments

Returns a list of payments. The payments are returned sorted by date.

DEFINITION
GET https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "payments": [{
    "id": 10,
    "date": "2015-01-20",
    "amount": "5.0",
    "formatted_amount": "$5.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  },
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in results set

NOTE: The list has been ordered by created_at.

Mark as Realized

DEFINITION
POST https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/[id]/mark_as_realized

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/invs/[invoice_hash_key]/payments/[id]/mark_as_realized \
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "payment": {
    "id": 10,
    "date": "2015-01-20",
    "amount": "5.0",
    "formatted_amount": "$5.00",
    "balance": "5.0",
    "formatted_balance": "$5.00",
    "payment_method": "paypal",
    "details": "Payment details",
    "combined_payment_details": "Paypal: Payment details",
    "currency_iso_code": "USD",
    "currency_symbol": "$",
    "payment_receipt_no": "RCPT-1",
    "payment_receipt_hash_key": "kiLDAgtGzNpaAQ",
    "state": "realized",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

NOTE: Offline payments are saved as unrealized payments. To mark them as realized, the user has to log into Hiveage and do so manually.

Items

The Item Object

You can save items for reuse in statements.

EXAMPLE OBJECT

{
  "item_category": {
    "id": 12,
    "name": "My Item",
    "description": "This is a sample item",
    "unit": "hourly",
    "price": "150.00",
    "formatted_price": "150.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Attribute Description
id integer Item ID
name string Item name, NOTE: When you search saved items to add as line items, you can search by item name or description.
description string Item descripton
unit string
price string
formatted_price string

Create a New Item

DEFINITION
POST https://[subdomain].hiveage.com/api/categories/items

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/items\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d item_category[name]="My Item" \
  -d item_category[description]="This is a sample item" \
  -d item_category[price]="150.00" \
  -d item_category[unit]="hourly" \


EXAMPLE RESPONSE
{
  "item_category": {
    "id": 13,
    "name": "My Item",
    "description": "This is a sample item",
    "unit": "hourly",
    "price": "150.00",
    "formatted_price": "150.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Parameter Description
name required Item name, NOTE: When you search saved items to add as line items, you can search by item name or description.
description optional Item descripton
unit optional Item unit
price required

Return

Returns the item object.

Retrieve an Item

Retrieve an item object with a specified id.

DEFINITION
GET https://[subdomain].hiveage.com/api/categories/items/[id]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/items/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{
  "item_category": {
    "id": 13,
    "name": "My Item",
    "description": "This is a sample item",
    "unit": "hourly",
    "price": "150.00",
    "formatted_price": "150.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Parameter Description
id required The id of the item object.

Returns

Returns an item JSON object if a valid item category id was specified. Returns an error otherwise.

Update an Item

Update a saved item.

DEFINITION
PUT https://[subdomain].hiveage.com/api/categories/items/[id]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/items/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d item_category[name]="My Item" \
  -d item_category[price]="200.00" \

EXAMPLE RESPONSE
{
  "item_category": {
    "id": 13,
    "name": "My Item",
    "description": "This is a sample item",
    "unit": "hourly",
    "price": "200.00",
    "formatted_price": "200.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Arguments Description
name required Item name, NOTE: When you search saved items to add as line items, you can search by item name or description.
description optional Item descripton
unit optional Item unit
price required

Returns

Returns an item JSON object if a valid item category id was specified. Returns an error otherwise.

Delete an Item

Deleting an item object permanently.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/categories/items/[id]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/items/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "item_category": {
    "deleted": true,
    "id": "13"
  }
}

Arguments

Parameter Description
id required The id of the item to be deleted.

Returns an object with a deleted parameter on success.

List All items

Returns a list of items. The items are returned sorted alphabetically.

DEFINITION
GET https://[subdomain].hiveage.com/api/categories/items

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/items\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "item_categories": [{
    "id": 13,
    "name": "My Item",
    "description": "This is a sample item",
    "unit": "hourly",
    "price": "200.00",
    "formatted_price": "200.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in the results set
order optional The list is ordered by name, and can be ordered by desc or asc. The defaul value is asc.

Expenses

The Expense Object

You can save expense categories for reuse in statements.

EXAMPLE OBJECT

{
  "expense_category: {
    "id": 12,
    "name": "Travelling",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Attribute Description
id integer Expense ID
name string Expense name

Create a New Expense

DEFINITION
POST https://[subdomain].hiveage.com/api/categories/expenses

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/expenses\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d expense_category[name]="Travelling" \


EXAMPLE RESPONSE
{
  "expense_category": {
    "id": 13,
    "name": "Travelling",
    "formatted_price": "150.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Parameter Description
name required

Return

Returns the expense object.

Retrieve an Expense

Retrieve an expense object with a specified ID.

DEFINITION
GET https://[subdomain].hiveage.com/api/categories/expenses/[id]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/expenses/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{
  "expense_category": {
    "id": 13,
    "name": "Travelling",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Parameter Description
id required The id of expense category object.

Returns

Returns a expense JSON object if a valid expense category ID was provided. Returns an error otherwise.

Update an Expense

Update an expense category.

DEFINITION
PUT https://[subdomain].hiveage.com/api/categories/expenses/[id]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/expenses/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d expense_category[name]="Foods" \

EXAMPLE RESPONSE
{
  "expense_category": {
    "id": 13,
    "name": "Foods",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Arguments Description
name required Expense name, NOTE: When you search saved expense cantegories to add one as a line item, you can search by item name or description.
description optional Expense descripton
unit optional Expense unit
price required

Returns

Returns a updated expense JSON object if a valid item ID was provided. Returns an error otherwise.

Delete an Expense

Deleting an expense object permanently.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/categories/expenses/[id]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/expenses/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "expense_category": {
    "deleted": true,
    "id": 13
  }
}

Arguments

Parameter Description
id required The ID of the expense to be deleted.

Returns an object with a deleted parameter on success.

List All Expenses

Return list of expenses. The items are returned sorted alphabetically.

DEFINITION
GET https://[subdomain].hiveage.com/api/categories/expenses

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/expenses\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "expense_categories": [{
    "id": 13,
    "name": "My Item",
    "created_at": "2014-07-21T11:04:58Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in result-set
order optional The list is ordered by name, and can be ordered by desc or asc. The defaul value is asc.

Tasks

The Task Object

You can save task categories for reuse in statements.

EXAMPLE OBJECT

{
  "task_category": {
    "id": 12,
    "name": "Development",
    "rate": "10.0",
    "formatted_rate": "10.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Attribute Description
id integer ID
name string Task name
rate string Task rate

Create a New Task

DEFINITION
POST https://[subdomain].hiveage.com/api/categories/tasks

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/tasks\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d task_category[name]="Development" \
  -d task_category[rate]="10.00" \


EXAMPLE RESPONSE
{
  "task_category": {
    "id": 12,
    "name": "Development",
    "rate": "10.0",
    "formatted_rate": "10.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Parameter Description
name required
rate string Task rate

Return

Returns the task object.

Retrieve a Task

Retrieve an expense object with a specified ID.

DEFINITION
GET https://[subdomain].hiveage.com/api/categories/tasks/[id]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/tasks/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{
  "task_category": {
  "id": 12,
  "name": "Development",
  "rate": "10.0",
  "formatted_rate": "10.00",
  "created_at": "2014-07-21T11:04:58Z"
}

Arguments

Parameter Description
id required The id of task category object.

Returns

Returns a task JSON object if a valid expense category ID was provided. Returns an error otherwise.

Update a Task

Update a task category.

DEFINITION
PUT https://[subdomain].hiveage.com/api/categories/tasks/[id]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/tasks/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d task_category[name]="Development" \
  -d task_category[rate]="20.0" \

EXAMPLE RESPONSE
{
  "task_category": {
    "id": 12,
    "name": "Development",
    "rate": "20.0",
    "formatted_rate": "10.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Arguments Description
name required
rate string Task rate

Returns

Returns a updated task JSON object if a valid task ID was provided. Returns an error otherwise.

Delete a Task

Delete a task object permanently.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/categories/tasks/[id]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/tasks/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "task_category": {
    "deleted": true,
    "id": "13"
  }
}

Arguments

Parameter Description
id required The ID of the task to be deleted.

Returns an object with a deleted parameter on success.

List All Tasks

Return list of tasks. The tasks are returned sorted alphabetically.

DEFINITION
GET https://[subdomain].hiveage.com/api/categories/tasks

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/tasks\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "task_categories": [{
    "id": 13,
    "name": "Development",
    "rate": "20.0",
    "formatted_rate": "10.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in results set
order optional The list has been ordered by name, and can be ordered by desc or asc. The defaul value is asc.

Trips

The Trip Object

You can save trip categories for reuse in statements.

EXAMPLE OBJECT

{
  "trip_category": {
    "id": 12,
    "name": "Travelling",
    "rate": "10.0",
    "formatted_rate": "10.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Attribute Description
id integer ID
name string Trip name
rate string Trip rate

Create a New Trip

DEFINITION
POST https://[subdomain].hiveage.com/api/categories/trips

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/trips\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d trip_category[name]="Travelling" \
  -d trip_category[rate]="10.00" \


EXAMPLE RESPONSE
{
  "trip_category": {
    "id": 12,
    "name": "Travelling",
    "rate": "10.0",
    "formatted_rate": "10.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Attributes

Parameter Description
name required
rate string Trip rate

Return

Returns the trip object.

Retrieve a Trip

Retrieve a trip object with a specified ID.

DEFINITION
GET https://[subdomain].hiveage.com/api/categories/trips/[id]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/trips/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

EXAMPLE RESPONSE
{
  "trip_category": {
    "id": 12,
    "name": "Travelling",
    "rate": "10.0",
    "formatted_rate": "10.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Parameter Description
id required The id of trip category object.

Returns

Returns a trip JSON object if a valid trip category ID was provided. Returns an error otherwise.

Update a Trip

Update a trip category.

DEFINITION
PUT https://[subdomain].hiveage.com/api/categories/trips/[id]

EXAMPLE JSON REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/trips/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \
  -d trip_category[name]="Development" \
  -d trip_category[rate]="20.0" \

EXAMPLE RESPONSE
{
  "trip_category": {
    "id": 12,
    "name": "Travelling",
    "rate": "20.0",
    "formatted_rate": "10.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
}

Arguments

Arguments Description
name required
rate string Trip rate

Returns

Returns a updated trip JSON object if a valid trip ID was specified. Returns an error otherwise.

Delete a Trip

Deleting a trip object permanently.

DEFINITION
DELETE https://[subdomain].hiveage.com/api/categories/trips/[id]

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/trips/[id]\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "trip_category": {
    "deleted": true,
    "id": "13"
  }
}

Arguments

Parameter Description
id required The ID of the trip to be deleted.

Returns an object with a deleted parameter on success.

List All Trips

Returns a list of trips. The trips are returned sorted alphabetically.

DEFINITION
GET https://[subdomain].hiveage.com/api/categories/trips

EXAMPLE REQUEST
$ curl https://[subdomain].hiveage.com/api/categories/trips\
  -H "Accept: application/json" \
  -u 6ZQHxidcLHnkcsnDbfM5: \

SAMPLE JSON RESPONSE
{
  "trip_categories": [{
    "id": 13,
    "name": "Travelling",
    "rate": "20.0",
    "formatted_rate": "10.00",
    "created_at": "2014-07-21T11:04:58Z"
  }
  {...},
  {...}]
}

The results will be paginated. You can use the following optional parameters to traverse the results.

Arguments

Parameter Description
per_page optional Number of results per page (default: 20). Available per page: 20, 60 and 100.
page optional Page in the results set
order optional The list is ordered by name, and can be ordered by desc or asc. The defaul value is asc.

Errors

The Hiveage API will respond with following HTTP status codes if an error occurs while processing your request. We expect the client code to catch these errors with a fallback mechanism.

Error Meaning
401 Access Denied – User is not authenticated. Please check whether you passed the correct api_tokenwith your request.
403 Forbidden – You dont have access to the requested resource (e.g – a module is not enabled) or you have exceeded the maximum request rate (please read the Rate Limiting section)
422 Bad Request – The request is not correctly formatted or is missing some parameters. Verify whether you have properly constructed the XML or JSON request and have included all the required parameters.
404 Not Found – Requested resource is not available.
500 Server Error – Something is wrong with the Hiveage server. Try again in a couple of minutes and if its a recurring error, please contact Hiveage support