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.