Set up API for event-based control triggering
Get an introduction into Impero's Control Management module here. We recommend you getting a basic understanding of the major components of a control and how a regular (recurring) control works, before setting up event-triggered controls. Check out this article. 😊
When do I need an API for control triggering?
You are observing irregular activities in your financial recordings or tax operations? Your robots or analytics tools are detecting anomalies in account activities or transactions?
This API enables you to further investigate and manage outliers or suspicious events. Whenever you need to send out adhoc controls, this API can help you.
Here are some examples:
- Obvious outliers: duplicate transaction, invoices without VAT
- Incorrect calculations: mistakes in accrual calculations or inventory devaluations
- Missing data: disclosure of deferred revenue, discount calculation
- Insufficient procedures: 4-eye principle, implementation of ICS guidelines
- Weaknesses investigation: employee safety procedures, information security
How to set up API for control triggering
Let's talk about our targeted workflow automation first 😊
Step I. 3rd-party systems inspect data and identify cases that require subsequent control measures.
Step II. 3rd-party systems send signals and necessary information on control design to Impero to trigger controls.
Step III. Impero sends out controls to investigate the identified cases in the defined control design automatically.
Now let's dive into Step II
At this stage, Impero's API allows you to send out adhoc/manual controls (NOT recurring), and to set three key information of the control design:
- Control title
- Control description
- Scheduling: due date as shown below
If needed, have a look at core elements of a control in Impero.
Note: We know that control triggering and the technical setting can look a bit complex. Please feel free to reach out to your Customer Success Manager or via firstname.lastname@example.org to go through it together. 💪
Very important: The following requirements need to be met to successfully trigger controls:
- The control assignment needs to be triggered from an existing control. So first create a control in Impero before using the API to update and send it out.
- The respective control program is active, which is per default.
- The control has at least one control responsible ensuring that the triggered assignment has a recipient.
- The due date is in the future. The notification date is in the past, which ensures that control assignments are sent out immediately once they are triggered. This avoids the situation that a control is NOT sent due to overwriting: The notification date (time of scheduled sending) for control no. 1 is not reached yet but the control is already updated again for control no. 2 - control no. 1 is overwritten and not sent.
- There are no previous control assignments (= those ones that had been already sent out) for this control with the same responsibles and the same due date and time avoiding that the same control is performed twice.
Can I see it with an example?
Note: Here is an set-up example using an API testing software. Please consult your IT team to connect Impero with systems from which you would like to trigger controls.
1. Generate an API key in your Impero environment: Read here.
2. Create a control in a desired control program: Check out here. Make sure to fulfill all described requirements above.
3. In the 3rd-party system, enter the following information:
a. Select the PATCH command
b. Enter the URL in a specific format as in the screenshot: e.g., https://imperodemode.impero.com/public-api/v1/controls/e7b4fbc7-b372-42d8-85a1-50fffd1fc773
Tip: How to create the PATCH URL in this required format?
Orgname is the first part of your Impero environment domain.
How to find control ID?
i. Go to the control program where the control is saved.
ii. Click on the control to open it.
iii. Copy the control ID from the URL that starts after "Edit/".
4. Choose "X-Api-Key" as the type of key and enter the API key you generated in your Impero environment.
Finally, it will look like this:
5. In the Body, write the control information in this format:
Control type needs to remain "Manual", as we currently only support triggering manual controls.
After entering the information, simply click on "Send".
An example for investigating duplicate transactions:
Read our API documentation to prepare the control in the required format.