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