Enrich via API
Using an API enrichment step in the builder to enrich raw data inputs with third-party APIs
Last updated
Using an API enrichment step in the builder to enrich raw data inputs with third-party APIs
Last updated
Once you're confident that your input data is formatted correctly, you're ready to integrate APIs that you can hit in order to enrich your data.
How might you use the 'Integrate API' step?
If you were building a pricing model for car insurance, you may want to use third-party APIs to return information that a customer may not know or may not input accurately, or you may simply want to save them time by only requesting one datapoint which you can then enrich with many other variables from a trusted source.
For example, you may want to use the registration plate of a vehicle inputted by a customer to return the vehicle's make from the DVLA API.
Once you've added the 'Integrate API' step and named it, like you will with any other step in the Build tool (more on that here), you'll need to add the API settings and secret keys for whichever third-party API you're using.
To get started, click the cog symbol in the top right of the 'Integrate API' step.
This guide assumes that a technical or development team has already set up a third-party API on your behalf.
For more information about how to set up an API, read our Developer API documentation.
Method - Here you can set the type of method you want to use to hit the API from the dropdown menu, choosing from three options:
'GET'
'POST'
'PUT'
Timeout - Here you'll select your API timeout in milliseconds. e.g. 1000
URL - This will be the URL you've been supplied with to hit the API, and should have the 'Output Key' that you want to send to the API in the URL string, so that it will dynamically be added each time your model quotes.
e.g. https://testapi.com/sw/enrich/dvla-vehicle/{{vehicle_reg_norm}}
Header Keys - This is where you'll populate the names of all header keys you've been given by the API provider.
Header Values - This is where you'll add the secret tokens you've been given from the API provider.
Data - This is where you enter the payload, and will likely be a blob of JSON. If you're unsure what should go here, consult your development or technical team - or the documentation for the third party API you're using.
You can click ‘Add Header’ at any time if you need to add additional rows of headers that may be required by the API, such as version credentials. These could be things like a username & password, additional tokens or API keys.
Once you've connected with an API, you can test the endpoint to make sure it returns the data you're expecting in the timeframe you need it to.
This will also allow you to see what variables the API will provide you with in the response, which will be helpful when you build out your properties table in the next step.
The last step is storing all of the variables you want to use from the API response for future use in your model.
If you don't want to store the variables in their raw format, you can do some simple transformation of that data using Swallow Syntax to reformat it the way you want.
For every variable you want to save, simply click the 'Add' button at the top right of the table to begin the process, and complete the fields below.
This labels the new variable you're saving. Keep the description short and simple so you can recognise it easily in future steps.
This is output name that will be passed to the next step, and how you'll reference the input in any syntax in future steps.
This will be auto-generated based on the label you've given, but you can edit it at any time.
This the data type of the data you want to transform the input into.
You can choose from 5 data types: Boolean, Decimal, Integer, String or Date.
To store the variable in its raw format with no transformation, simply write the expression in brackets, with the variable as it is named in the API response between curly brackets - e.g. ({{make}}).
To do some simple transformation of the data, check out our full page on Syntax. Here you can learn how to structure your expression in more detail, debug and see a full glossary.
This is the default value you want to set.
This is the data the model will default to if the value is not defined by the customer or the transformation fails for any reason.
Once you're happy with the settings of the variable you're adding, just press the 'Save' button in the bottom right of the modal and you're ready to add more variables to the table if you want to.
Once you're happy with all of your variables, just press the 'Save' button in the top right of the screen. You're now ready to head back to the 'Build' screen.
