Scraping Companies House data for your Salesforce Accounts with Hooked
We take you through using Hooked to retrieve data from Companies House
As part of our series on real life use-cases with our solutions, today we’re going to have a look at Hooked, our declarative webhook builder for Salesforce.
Using Hooked you can send data to external systems and even save returned data back into Salesforce — all without having to write a single line of code.
In this blog we’ll be using the free Companies House API to populate Salesforce Account information automatically when an account gets created!
Before getting started you will need to register on Companies House for a developer account to get your free API token, as well as install Hooked in your Salesforce org. (Hooked is free for 30 days, and free for up to 2 webhooks after the trial, so plenty of time to test it out with no commitment!)
Companies House API
Companies House is the United Kingdom’s registrar of companies, and they provide a free lookup service to find out key information for any UK registered company.
You can create an account here for free:
https://developer.companieshouse.gov.uk/developer/signin
Once you do that you can then create an ‘application’, which gives you an API token. You’ll need this token later to use in Hooked!
Installing Hooked
To get started with Hooked you first need to install it from the AppExchange (it’s free!) and once installed give yourself the “Hooked Admin” permission set. You’ll then be able to navigate to the “Webhook Builder” tab to get started.
Click on ‘New’ and fill in the following information:
Webhook Name — Any name you like
Description — Something to remind you what the webhook is for
Object — ‘Account’
Apex Label — Leave the default value
Once you click save Hooked will actually go and deploy a trigger on the Account object for you ready to be used with your configuration! You’ll be taken to a very familiar screen that looks like Process Builder — this is where we decide how our webhook works!
Click on the “Add Trigger” button and select “After Insert”. This means our webhook action will run after an Account is created— just like a normal Apex Trigger.
You’ll then see the option to set “Filter Criteria”, “Field Mapping”, and an “Endpoint Target”. For now we’ll leave “Filter Criteria” blank, which means any Account will trigger the webhook when created.
Under “Field Mapping” we can choose the fields that are sent to our endpoint. Let’s add a new field with the “Add Field” button, and set the following values:
Key — Id
Value — Account ID [Id]
As you add fields you’ll see a preview of the exact JSON that will be sent to the external system.
Setting Endpoint Details
If we have a look at the Companies House API documentation we can see all the different endpoints available. In this example we’re going to use the “Company profile” endpoint, which asks for a company number and in return gives us all the details around that company.
As we can see, the endpoint we need is:
https://api.companieshouse.gov.uk/company/{company_number}
The {company_number} is dynamic, so how do we set that? Luckily Hooked allows you to use merge fields in your endpoints, so we can use the following as our endpoint target:
https://api.companieshouse.gov.uk/company/{!record.AccountNumber}
As we add our URL we’ll see Hooked telling us to add “https://api.companieshouse.gov.uk” to our Remote Site Settings. This is done to grant Salesforce access in sending data off the platform.
If you click the link you’ll be able to add a new Remote Site, with the following details:
Remote Site Name — CompanyHouse
Remote Site URL — https://api.companieshouse.gov.uk
Active — CHECKED
We also need to add our authorization token we generated earlier to grant us access to the Companies House API. To do this click on the settings “Cog” icon next to the endpoint section in Hooked and you’ll see a new popup.
We need to ensure the “Endpoint Method” is set to GET, as this is what the Companies House API tells us is required.
We also need to set a header with the following values:
Header — “Authorization”
Value — The token you generated earlier!
For now, let’s save our progress from the top-right, and click the “Activate” button to activate the webhook! Now we can test it out.
Testing Our Webhook
Let’s go and create a new Account with the following details:
Name — Appitek
Account Number — 10589877
Once created nothing will happen, but a new “Webhook Debug Log” will have been created, as we have set “Debug Logs” to be active for our Webhook! Head over to the “Webhook Debugs Logs” tab and view the latest record created.
As we can see in the “Response” field, the Companies House API sent us some JSON back with loads of details back for our Account Number! Now it’s no good sitting in the debug log, we want it on the Account record — so let’s look at mapping the response.
Mapping Responses
Now we know the webhook works and the endpoint returns data, we can look at mapping the data back into Salesforce.
Go back to the “Webhook Builder” tab and open up the webhook you created, then re-open the endpoint settings using the “Cog” icon.
Under the headers you’ll see an area to “Add Mapping”. (Note: you can only see this on AFTER triggers, so make sure you set the trigger group to AFTER INSERT for this example!). Add the following mappings:
company_name — Text — Account Name
registered_office_address.address_line_1 — Text — BillingStreet
registered_office_address.country — Text — BillingCountry
registered_office_address.locality — Text — Billing City
registered_office_address.postal_code — Text — Billing Postal Code
By using the dot notation, we can traverse down the JSON response of the server to get nested values. In this case the “registered_office_address” key contains more keys for the address information.
Now let’s save our changes and go and re-create the same Account as we did earlier, using an Account Number of “10589877”.
Once saved, refresh the page and you’ll see a bunch of data mapped automatically to the Account!
Give it a go!
Follow this guide along yourself and see just how easy it is to set up an outbound integration without ever having to look at a single line of code. Plus you can use it in both Salesforce Classic & Salesforce Lightning!
There’s loads of great use-cases for Hooked — anywhere you want to send out details of a new record, or retrieve data for a given record. For a more advanced example why not try setting up a contact database aggregator like RocketReach to update your contact information when they get created!
Hooked is completely free for 30 days with no card details required, and after that if you only want to use up to 2 webhooks it’s still completely free!
Let us know how you get on in the comments below! If you want to learn more about Hooked try the following resources:
Documentation:
https://appitek.com/documentation/hooked.html#Introduction
“Getting Started” Guide
https://appitek.quip.com/JtpuAgYm2eIA/Getting-started-with-Hooked
“Introduction to Hooked” Blog
https://appitek.com/blog/hooked-the-declarative-webhook-builder-for-salesforce
At Appitek, our aim is to help make your job easier, by creating simple but effective Salesforce applications that make you more efficient at what you do.
Appitek is a registered Salesforce ISV partner.
Salesforce and Salesforce Lightning are registered trademarks of Salesforce.com
