API Documentation

Authentication

Authenticate your account when using the API by including your secret API key and your CompanyHub subdomain in the request. You can see/manage your API keys from SettingsIntegrations. You can have maximum of 5 API keys. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such your source control if it is public, client-side code, and so forth.

Authentication to the API is performed via custom authentication. You will have to provide your CompanyHub Subdomain and any of the API keys in Authorization header for authentication.

Versioning

Currently, CompanyHub is in v1 of API. So base API url is https://api.companyhub.com/v1/

Pagination

All top-level API resources have support for pagination. For instance you can list contacts, list companies, and list deals. These list API methods share a common structure, taking at least these two parameters: start, limit.

You get Total property in response to calculate no of pages and then decide the values of start and limit parameters. Start parameter skips the page whilst limit parameter limits the no of records per page.

Errors

CompanyHub uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success and codes in the 5xx range indicate an error with CompanyHub’s servers (these are rare!).

Not all errors map cleanly onto HTTP response codes, however, you will get the error in the errors section of the response. You can check errors section if Success property in response is false.

For each error, you will get a generalized error in Message property of response. You can check fieldwise errors in detail in Errors array. Here is the sample error response.

{
	"Success": false,
	"Message": "Either First Name or Last Name must be specified.",
	"Errors": {
		"FirstName": {
			"Errors": ["Either First Name or Last Name must be specified."]
		},
		"LastName": {
			"Errors": ["Either First Name or Last Name must be specified."]
		}
	}
}

You can also get errors if you are trying to perform an operation not permitted to you by your Admin. Admin can revoke/grant you permissions which can limit/extend the number of operations you can do. If you do not have permission to perform a certain operation, you can get such error in the response.

Know your table names and field names

To see the names of table and fields, go to SettingsCustomizeTables. Click on the table name. Now you can see the names of the table and fields. Make sure not to use the labels in API.

What can you access in API?

Currently, you can access standard tables like Contact, Company, Deal and all the custom tables you have created along with the fields you have access to.

You cannot access fields if you don’t have permission to read those fields. Also, you cannot update the fields you don’t have edit access to.

Resources

Test Authentication

You can test authentication with Companyhub.

Request:

Definition:GET  https://api.companyhub.com/v1/me

Headers:Authorization:  {your_subdomain} {your_api_key}Content-Type:  application/json

Response:

{
"Name": "John Doe",
"EmailAddress": "[email protected]",
"IsSandbox": false,
"Subdomain": "doebiz"
}

Get All Records

Returns a list of your records for a specified table. The records are returned with the most recent records appearing first in the response. You can paginate the records using pagination parameters.

Request

Definition:GET  https://api.companyhub.com/v1/tables/{tableName}

Headers:Authorization:  {your_subdomain} {your_api_key}Content-Type:  application/json

Response:

{
	"Total": 2,
	"Data": [{
		"ID": 2,
		"Name": "Danish Deshmukh",
		"FirstName": "Danish",
		"LastName": "Deshmukh",
		"Email": "[email protected]",
		"Company": {
			"ID": 1,
			"Name": "Site"
		},
		"Phone": "6666666666",
		"Designation": "Customer Success Manager",
		"Source": "Web",
		"NextFollowUpDate": "2018-01-17T00:00:00",
		"Description": "Danish Deshmukh is the Customer Success Manager at CompanyHub, in case of any Technical/Billing related queries we can reach out to him at his email.",
		"Twitter": null,
		"LinkedIn": "https://in.linkedin.com/in/danish-deshmukh-92155963",
		"GooglePlus": "https://plus.google.com/u/0/111900785578054685673",
		"Facebook": "https://www.facebook.com/danish.deshmukh.71",
		"Skype": null,
		"Street": null,
		"City": "Nashik",
		"State": "Maharashtra",
		"Country": "India",
		"PostalCode": "422101",
		"NoFollowups": false,
		"Hotness": "Unknown",
		"Owner": {
			"ID": 1,
			"Name": "John Doe"
		},
		"CreatedOn": "2018-01-18T08:07:47",
		"CreatedBy": {
			"ID": 1,
			"Name": "John Doe"
		},
		"ModifiedOn": "2018-01-18T08:07:47",
		"ModifiedBy": {
			"ID": 1,
			"Name": "John Doe"
		}
	}, {
		"ID": 1,
		"Name": "Abhishek A Agrawal",
		"FirstName": "Abhishek",
		"LastName": "A Agrawal",
		"Email": "[email protected]",
		"Company": {
			"ID": 1,
			"Name": "CompanyHub"
		},
		"Phone": "9999999999",
		"Designation": "CEO",
		"Source": "Web",
		"NextFollowUpDate": "2018-01-17T00:00:00",
		"Description": "Abhishek is passionate about technology and entrepreneurship. He is always looking to leverage technology for growth of business.",
		"Twitter": "https://twitter.com/abhipreneur",
		"LinkedIn": "https://in.linkedin.com/in/abhipreneur",
		"GooglePlus": "https://plus.google.com/u/0/117476859949086684278",
		"Facebook": "https://www.facebook.com/profile.php?id=572950163",
		"Skype": "agr.abhi",
		"Street": null,
		"City": "Nashik",
		"State": "Maharashtra",
		"Country": "India",
		"PostalCode": "Site",
		"NoFollowups": false,
		"Hotness": "Unknown",
		"Owner": {
			"ID": 1,
			"Name": "John Doe"
		},
		"CreatedOn": "2018-01-18T08:07:47",
		"CreatedBy": {
			"ID": 1,
			"Name": "John Doe"
		},
		"ModifiedOn": "2018-01-18T08:07:47",
		"ModifiedBy": {
			"ID": 1,
			"Name": "John Doe"
		}
	}],
	"Success": true,
	"Errors": {}
}

Get Particular Record By ID

Retrieves the details of an existing record from specified table. You need to supply the unique record identifier that was returned upon record creation i.e. ID field for the record.

Request:

Definition: GET  https://api.companyhub.com/v1/tables/{tableName}/{ID}

Headers: Authorization:  {your_subdomain} {your_api_key}Content-Type:  application/json

Response:

{
	"Total": 1,
	"Data": {
		"ID": 2,
		"Name": "Danish Deshmukh",
		"FirstName": "Danish",
		"LastName": "Deshmukh",
		"Email": "[email protected]",
		"Company": {
			"ID": 1,
			"Name": "CompanyHub"
		},
		"Phone": "6666666666",
		"Designation": "Customer Success Manager",
		"Source": "Web",
		"NextFollowUpDate": "2018-01-17T00:00:00",
		"Description": "Danish Deshmukh is the Customer Success Manager at CompanyHub, in case of any Technical/Billing related queries we can reach out to him at his email.",
		"Owner": {
			"ID": 1,
			"Name": "John Doe"
		},
		"Twitter": null,
		"LinkedIn": "https://in.linkedin.com/in/danish-deshmukh-92155963",
		"GooglePlus": "https://plus.google.com/u/0/111900785578054685673",
		"Facebook": "https://www.facebook.com/danish.deshmukh.71",
		"Skype": null,
		"Street": null,
		"City": "Nashik",
		"State": "Maharashtra",
		"Country": "India",
		"PostalCode": "422101",
		"CreatedOn": "2018-01-18T08:07:47",
		"CreatedBy": {
			"ID": 1,
			"Name": "John Doe"
		},
		"ModifiedOn": "2018-01-18T08:07:47",
		"ModifiedBy": {
			"ID": 1,
			"Name": "John Doe"
		},
		"NoFollowups": false,
		"Hotness": "Unknown"
	},
	"Success": true,
	"Message": "",
	"Errors": {}
}

Create Record

Creates a record in the specified table and it returns the ID of record for further use. For instance, to associate in a related record.

Request:

Definition: POST  https://api.companyhub.com/v1/tables/{tableName}

Headers: Authorization:  {your_subdomain} {your_api_key}Content-Type:  application/json

Body:

{
  "FirstName":"John",
  "LastName":"Doe"
}

Response:

{
	"Id": 3,
	"Success": true,
	"Errors": {}
}

Edit Record

Updates the specified record by setting the values of the parameters passed. Any parameters not provided will be left unchanged.This request accepts mostly the same arguments as the record creation call along with the ID field.

Request:

Definition:PUT  https://api.companyhub.com/v1/tables/{tableName}/{ID}

Headers:Authorization:  {your_subdomain} {your_api_key}Content-Type:  application/json

Body:

{
  "LastName":"Doe"
}

Response:

{
	"Success": true,
	"Errors": {}
}

Delete one or more records

Deletes records of a specified table identified by IDs. You can recover deleted data for upto 30 days after which it is permanently deleted.

Request:

Definition:DELETE  https://api.companyhub.com/v1/tables/{tableName}

Headers:Authorization:  {your_subdomain} {your_api_key}Content-Type:  application/json

Body:

{
	"deletedIds": [{ID1},{ID2}]
}

Response:

[{
	"Success": true,
	"Errors": {}
}]

How can you filter records?

There are two ways in which you can filter the records.

Filter records for searches

You can use this to search records in CompanyHub when you want to show them in autocompletes or something similar where you don’t need accuracy. It is less accurate as it will search queried value in all fields on each record of the specified table. You can’t tell the field in which you want to search your query.

Request:

Definition:GET  https://api.companyhub.com/v1/tables/{tableName}?searchText={url_encoded_query}

Headers:Authorization:  {your_subdomain} {your_api_key}Content-Type:  application/json

Response:

{
	"Total": 2,
	"Data": [{...},{...}],
	"Success": true,
	"Errors": {
		
	}
}

Filter records for exact matches

When you want to assign lookups which require exact matches, you can filter or find the records by using the field name and query value.When you are doing something in API and you want to assign values or find records where certain field has a specific value, you can use this exact search.

You can use various operators such as: eq, ne, lt ,gt, le, ge etc.

Request:

Definition:POST  https://api.companyhub.com/v1/tables/{tableName}/search

Headers:Authorization:  {your_subdomain} {your_api_key}Content-Type:  application/json

Body:

{
  "Where": [
    {
      "FieldName": "FirstName",
      "Operator": "eq",
      "Values": ["dan"]
    }
  ]
}

Response:

{
	"Total": 2,
	"Data": [{...},{...}],
	"Success": true,
	"Errors": {
		
	}
}

PHP Library

A simple library to consume CompanyHub API in PHP available at GitHub

Usage

Include and init CompanyHub with credentials

include 'CompanyHub.php';

//COMPANYHUB API DETAILS
$domain = "YOUR_DOMAIN";
$secret = "YOUR_SECRET";

$companyHub = new CompanyHub($domain, $secret);
	

To test authentication

$response = $companyHub->getData("/me");
echo "GET : " . $response ;

To get all records of a table

$response = $companyHub->getData("/contact");
echo "GET : " . $response;

To get a particular record by ID

$response = $companyHub->getData("/contact/1");
echo "GET : " . $response;

To create new record

$fields = array('Name' => 'Vivek Muthal');
$response = $companyHub->postData("contact", $fields);
echo "POST : " . $response;

To update a record by ID

$recordId = 1;
$fields = array('Name' => 'Vivek MuthalUpdated');
$response = $companyHub->postData("contact", $fields, $recordId);
echo "PUT : " . $response;

To delete single or multiple records

$deleteIds = array('deletedIds' => array(1,2,3));
$response = $companyHub->deleteData("contact", $deleteIds);
echo "DELETE : " . $response;