API Advanced - CRM Integrations

Last reviewed: 03/08/23

Integration with a CRM system

A common use of the Barbour ABI platform is to cherry-pick projects for upload into a CRM system such as Salesforce or Microsoft Dynamics. The tags feature within the Barbour ABI platform is the best way to achieve this.

To implement a CRM integration, a software developer will need to use the Barbour ABI APIs. If you do not have a software developer, please speak to Barbour ABI who can put you in touch with integration partners.

This supplementary API document is aimed at software developers to explain the implementation approach.

Requirements

Each user will require a Web license to access the Barbour ABI platform to tag projects.

The developer will require a Web license for the initial set up and support, plus a developer license giving them to access the Barbour ABI APIs for use in their integration code.

Initial setup

As a one-off task the developer should sign into the Barbour ABI Platform https://app.barbour-abi.com to create a shared tag as follows:

  1. View an arbitrary project and add a tag, for example ‘Add to CRM’.
  2. Go to ‘My leads’ (left hand menu) and click the ‘Tags’ tab
  3. Click ‘Add to CRM’ to see the list of projects (will be just one) with this tag
  4. Click ‘Share’ and share with ‘Everyone’. This will allow all users to use this tag.

Process flow

Authenticate

Authenticate to get a token for all subsequent API calls. Full details about authenticating, along with an example are provided in the main Barbour ABI API documentation.

Get the tag_id

Each tag in the Barbour ABI platform has an internal id, named tag_id. This is not visible via the web interface, so needs to be obtained as follows:

				
					GET tags
				
			

This will return all the tags for your developer user account:

				
					{
    "tags": [
        {
            "tag_id": 4810,
            "tag_name": "Add to CRM",
            "is_priority": true,
            "is_shared": true,
            "created_by": 409,
            "count": 1,
            "project_count": 1,
            "company_count": 0
        },
        ...

				
			

Users can only delete their own tags using the Web interface, so there is little chance of this tag disappearing. However, if you as the tag owner delete it and recreate it, then it will get a new tag_id.

Extract tagged projects

Get a list of all the projects with the ‘Add to CRM’ tag as follows:

				
					GET projects?tag_id={tag_id}
				
			

If the roles, companies and people working on the project are not required for the integration, then the fields parameter can be used to get the required project fields in a single API call:

				
					GET projects?tag_id={tag_id}&fields=project_id,project_title,project_value
				
			

If a large number of projects have been tagged, the limit and offset parameters should be used to iterate through the results. This will be an unlikely scenario if you are making regular API calls to process the tagged projects.

To get the full set of details for a project, iterate through the list of project_ids, making this API call to get the full project details:

				
					GET projects/{project_id}
				
			

With this API call the fields parameter can be used if specific fields are required.

The roles, companies and people for the project can be obtained with a single API call by using the fields parameter to specify your preferred fields as follows:

				
					GET projects/{project_id}/roles?fields=company_name,company_phone,person_first_name,person_last_name
				
			

Or alternatively omit the fields parameter to get a list of company_ids and person_ids working on the project.

A single or many companies can be obtained as follows:

				
					GET companies/{company_id}

GET companies?query={
   "company_id":{
      "operator": "=",
      "value": [{company_id},{company_id}]
   }
}

				
			

A single or many people can be obtained as follows:

				
					GET people/{person_id}

GET people?query={
   "person_id":{
      "operator": "=",
      "value": [{person_id},{person_id}]
   }
}
				
			

Customers often want to assign the projects to the appropriate users within their CRM system. To find out which user tagged the project:

				
					GET projects/{project_id}/tags

				
			

The response will include “tagged_by”, the user_id of the person who created the tag.

To get the name associated with a user_id:

				
					GET users/{user_id}
				
			

The list of users names should be cached in your code, rather than making continuous calls to this API.

Stop future processing

To avoid reprocessing the project later, the ‘Add to CRM’ tag should be removed from the project as follows:

				
					DELETE projects/{project_id}/tags
{
      "tag_id": 3
}

				
			
Mark as uploaded for the user

Rather than users depending on the disappearance of the ‘Add to CRM’ tag to indicate the project has been uploaded to your CRM system, either add a new tag or add a note.

Option A: Add a tag

During the initial setup, create a second shared tag, named “CRM”. This tag will indicate the project has been successfully added to their CRM system.

Add this tag to the project as follows:

				
					POST projects/{project_id}/tags
{
      "tag_id": xxx
}
				
			

There is nothing in the Barbour ABI platform to prevent users from removing this tag from the project. If this is a traceability concern, adding a note may be preferable.

Option B: Add a note

Add a note to the project to indicate the process is complete, as follows:

				
					POST projects/{project_id}/notes
{
   "note" : "Uploaded to CRM for Giles Armitage"
}
				
			

The note could be customised with the users name, as per the example above.

This note will be available to all users in the Collaborations section within “Activities” on the project details page.

Users cannot delete other users notes.

Keeping projects updated

Barbour ABI researchers track projects, adding roles, companies and updating project information as the projects progress. Some customers simply insert projects into their CRM system and never update them, leaving their staff to make any updates they wish.

Other customers upsert (insert + update) the projects into read-only fields within their CRM system and update these fields as Barbour ABI provide updates. If you prefer the latter approach, there are two methods to get the updates:

Option A: Request all updates

Use the APIs to get a list of all the projects updated by Barbour ABI in the last n days as follows:

				
					GET projects?query={
   "project_last_published":{
      "operator": ">=",
      "value": -1
   }
}
				
			

In this example. the “-1” is one day ago, so yesterday.

For each of these projects, check in your CRM system to see if it exists. If it exists, then update the fields.

We recommend performing these project updates daily, rather than weekly because posting large volumes of data to CRM system is sometimes constrained by the vendor.

Option B: Request specific updates

Get a list of the project_ids from your CRM and use the Barbour ABI APIs to see if these have been updated in the last n days:

				
					GET projects?query={
   "project_id":{
      "operator": "=",
      "value": [{project_id},{project_id}]
   },
   "project_last_published":{
      "operator": ">=",
      "value": -1
   }
}
				
			

This will provide you with just the projects you need to update in your CRM system.

If you have a large number of project_id’s in your CRM system, then use option A would be preferable, otherwise you will need to break the project_ids into groups of 100 and make a separate API call for each group of projects.

Any questions?

For support using the Barbour ABI APIs, please sign into the Barbour ABI platform and use the “Chat with us” functionality in the bottom left of the Web platform.

Get a Free Trial

Just fill in your details below and a member of our team will give you a call.

Book a Demo

Helping Contractors

Win More Business

Get in touch with us and see how we can help you win more work.

FIND YOUR

10 FREE

PROJECT LEADS TODAY

Barbour ABI White Logo

Place of registration: Barbour ABI Limited Company number: 13427982, Registered office: 5th Floor, 133 Houndsditch, London, EC3A 7BX