Getting Started with the AUTTO API

The AUTTO API is used to connect to applications that do not have direct integrations with AUTTO.

To ensure that the AUTTO API is clearly understood, this article takes the form of a short tutorial on creating an API call, and a workflow that uses the API call in a Get Data Action. You will then run the workflow on the User Application.

This article discusses how to get started using the AUTTO API in more detail.

Table of Contents

• Introduction
• Prerequisites
• Signing Up for an API Account
  • To Generate the API Key
• Creating the API Call
  • To Test the API Call
• Creating the Workflow
  • To Use the API Call in the Workflow
  • To Display the Results from the Get Data Action
• How does the API Call Appear in the Workflow

Introduction

There are three (3) things needed to start using the AUTTO API.

• Sign up for an account to access the API and create an API key
• Create an API call using the API key and other API-related information on the AUTTO API Manager
• Create a Workflow with a Get and/or Send Data action that uses the API call

NOTE: Familiarity with web applications development may be needed when working with APIs.

Prerequisites

Before you can start using API calls in a workflow, you must first need to set up the following:

• An account with access to the other application's API
• An API call, which can be any of the following types:
  • GET API request
  • POST API request
  • PUSH API request
  • PATCH API request

NOTE: AUTTO facilitates setting up integrations with Microsoft 365, Microsoft Dynamics, Salesforce, Slack, and Google APIs, e.g. Gmail, Google Calendar, and Google Docs, among other Google applications, via API Manager Integrations. You can then set API requests to these services from the AUTTO API Manager. For more information, see Using the AUTTO API Manager.

Signing Up for an API Account

API providers normally require users to have an account with them before you can use their API.

For our purposes, we will create a GET API call using the Companies House API, which is a REST API that provides data related to UK-registered companies. This will require signing up for a Companies House API account here.

We will use the Companies House API to get company information that we will then use in our workflow. For more information on getting started with the Companies House API, click here.

To Generate the API Key

Aside from an account, APIs require an API key to be generated for your applications before they can provide access to their data. Some APIs provide a single API key while others, like Companies House API, may provide more than one API key.

After creating a Companies House account, you need to add AUTTO as an application in your Companies House API dashboard and generate an API key for AUTTO. For more information on how to generate an API key for the Companies House API, click here.

The API key is sent with each request to the Companies House API, as it serves as the authentication credentials to the API. If an API key is not generated, you will not be able to retrieve data from the API.

Once AUTTO is added as an application and an API key for it has been generated, it will appear in your list of applications on your Companies House dashboard.

Creating the API Call

After signing up for a Companies House API account and getting an API key for AUTTO, you can start creating the GET API call.

Our API call will take a company's registration number as an input, and output the company address based on the company registration number. Details about the Company Profile endpoint we will be using  can be found here.

NOTE: Endpoints specify the resources that can be accessed by third-party applications. The access is via a Uniform Resource Identifier (URI) to which HTTP requests are posted, and from which the response or return value is expected.

To create the API call:

1. On your Dashboard, click the Main Menu, then API Manager.
2. On the top right of the API Manager, select New API GET Call from the list, then click Create to display the fields for defining the API call.
3. Enter a name for the API call, then a description. You can use any name for now, but it is recommended that the API call be more descriptive to avoid any confusion when you start creating more calls.
4. Click the API URL button, then enter https://api.companieshouse.gov.uk/company/{company_number} as the API URL.
5. Under the Query Parameters section, enter company_number as the parameter name. You may also enter an optional description of the parameter at this time.
6. Click API Headers, then enter Authorization as the header name and your API key as the header value.
   
   
   
   
7. Click Response Map, then add an Address API response and name it Company Address.
8. Under the different JSON keys corresponding to the Add API response, enter the expected values for the Company Profile resource, details of which can be found here.
   
   
   
9. Click Done.

NOTE: For more information on creating API calls in AUTTO, see Using the AUTTO API Manager.

To Test the API Call

To ensure that the API call is defined correctly, test the call and verify that it is passing the correct parameters and retrieving data correctly from the API.

To test the API call:

1. Under the Test API section of the API call you just created, enter a company registration number as the query parameter value. For our purposes, we are using AUTTO's own company number, 10143556.
2. Click Test. The test response from the API is then displayed below. Look for the "mappedData" section and see if the response values are mapped correctly under the API call.
   
   

Creating the Workflow

We will then create a normal workflow with a Form action with a Text question, and a Get Data action that will use the GET API call we created in Creating an API Call. We will use the Get Data action to retrieve the company name from the Companies House API. We will then display the retrieved information in a Page action in our workflow.

To create the workflow:

1. Create a workflow. For more information, see Creating a Workflow.
2. Add a Form action to the workflow. For more information, see To Use Actions in a Workflow.
3. Add a Number question to the Form action that asks the user to enter the company registration number to be searched. For more information, see Number Questions.
   
   
   
   
4. Click the x button on the top-left of the Action Editor to save and close the Form action.

To Use the API Call in the Workflow

To use the API call in our workflow, we need to set up a Get Data action and use it in our workflow.

1. Add a Get Data action to the workflow. For more information on the Get Data action, see Get Data Action.
2. On the Action Editor for the Get Data action, select the API call you created in Creating the API Call from the list.
3. Under the Inputs section, enter the square bracket for the parameter which will be sent with the API GET request. Since we have asked our users to provide the company registration number, the square bracket for the company registration number we defined when we created the workflow should be entered here. In our example, we are using the company_number square bracket.
4. Under the Outputs section, enter the expected output from the API call. Since we will be getting the company address corresponding to the company registration number we entered in Step 3, our expected output is Company Address, which we will save into a company_address square bracket using the provided box to the right.
   
   
   
   
5. Click the x button on the top-left of the Action Editor to save and close the Get Data action.

To Display the Results from the Get Data Action

You can now finalize the workflow.

1. Add a Page action to the workflow. For more information, see Page Action.
2. Set up the Page action so that it will display the Company Address retrieved by the Get Data action from the Companies House API. For more information on how to go about formatting the Page action, see Table Square Brackets.
   
   
3. Unless you want to add another Action to the workflow, click Advanced Options, then check the Set Page as workflow end box.
   
   
4. Click the x button on the top-left of the Action Editor to save and close the Page action.
5. Preview, then publish the workflow to see it in action.

NOTE: When an API call is used in a workflow, it displays a Lock sign on the API Manager, meaning that any changes to the API call may affect the published workflow and potentially cause problems. In this case, you can only edit the API call upon entering your password.

How does the API Call Appear in the Workflow

API GET calls retrieve data while POST, PUT, and PATCH calls create or update server resources. Response data from API calls can be shown to your users by posting them in your workflow's Actions, such as the Page action that we created in To Display the Results from the Get Data Action.

In the case of PATCH calls, the resource server will send a response that the call has been successful. However, the response will not include any other details. You can use a GET after a PATCH to check that the fields have been updated.