Build and manage all your integrations directly in FreeAgent CRM. You can then use these integrations with our Workflow engine to create very powerful flows.
User Permissions: Only Admins can create new Integrations.
Note: Integrations exist in a low-code environment. Some JavaScript is required to create and manage these. Integration tutorials will cover this.
In this tutorial, we will cover the basics of creating new Integrations directly within your FreeAgent platform. We will then set up a DocuSign Integration to implement this powerful feature.
Navigate to Integrations
Go to Settings > Integrations > Integrations, or simply start typing 'Integrations' in the menu search to find the option faster.
Generating the FreeAgent API Key
On the Integrations page click on the "Generate API Key" Button. You'll then be asked to enter the email address you use to log in to FreeAgent.
Create New Integration
All new integrations require a series of steps in order to be completed. To get started, you need to give your Integration a name and, optionally, add a description for it.
Now let's review the steps, one at a time:
| STEP | DESCRIPTION |
| 1. Authentication | There are two authentication types supported: OAuth or Custom Auth. |
| 2. Connectors | Calls to the 3rd party service API endpoints. |
| 3. Testing | Review the logs and returned output of your Integration. |
| 4. Authorize | Runs the Authentication flow. |
1. Authentication
There are two authentication types supported: OAuth or Custom Auth.
OAuth
This authentication option requires the following configuration:
| CONFIGURATION | DESCRIPTION |
| OAuth URL | The URL of the 3rd party service for the user to authorize the integration. |
| Queryparams for OAuth URL |
Parameters appended to the OAuth URL. They depend on the service you are integrating with. Requires a 'Callback' to FreeAgent. |
| OAuth Callback Code | Brings back the Authorization code and generates the Access Token. This is stored so that the user doesn't need to authenticate every time. |
| Configuration |
Here you can store unique values such as: integrationKey To then use them in the OAuth Callback Code. |
| Authentication Code | Gets the Access Token and Refresh Token. It is constantly reviewing that the Access Token continues to be valid. |
Custom Auth
This authentication option supports other authorization types when OAuth is not available.
2. Connectors
These are created to call API endpoints. You can create as many connectors as needed for your Integration, one for each API call to the 3rd party service API. Each connector requires the following configuration:
| CONFIGURATION | DESCRIPTION |
| Name | Identifies the connector. Ie. Send for eSign |
| Description |
Optional. Additional information about the connector. |
| Input Parameters |
These are the expected values. For each parameter, you should define its: Property |
| Connector Custom Code |
Custom code. Depends on what is expected from the connector. |
| Output Parameters |
Expected result. |
3. Testing
It is important to test each step during the Integration creation. For this, you don't need to finish the complete integration along with the Workflow, as you can test it during its creation phase. To test your integration, just click the 'Test' button located in the top right corner of the Integration detail page. Here you can choose to test the Authentication flow or each of the connectors.
For the Authentication, there are two main sections:
- Debug logs show the console.logs you have within your code.
- The returned output shows the complete output.
To test the connectors, select one and then click the 'Test' button. This will open a new window where you will be requested the input parameters you want to use to test. Type in the values for the inputs and click the 'Test' button.
There are two main sections in the Test results of the connectors:
- Connector Results, which shows the returned output.
- Integration Results, which show the debug logs for the authentication process.
4. Authorize
It is important that when you have completed the Authentication step you Authorize the integration. This will grant your integration the required Access Tokens. You only need to do this once, when you first create your Integration.
Note: If the password of the 3rd party service is changed, you will need to go through the Authorize process again.
To authorize your Integration, go to its detail page and click the 'Authorize' button located in the top right corner, next to 'Test'. Doing this will open a new window to the OAuth URL specified during the Authentication step. Here you will need to enter the credentials of the 3rd party service account.
If you click the 'Test' button after you have Authorized your Integration, you will see it under the "Last authorized at" date.