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.