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.