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:
- View an arbitrary project and add a tag, for example ‘Add to CRM’.
- Go to ‘My leads’ (left hand menu) and click the ‘Tags’ tab
- Click ‘Add to CRM’ to see the list of projects (will be just one) with this tag
- 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.