Import data from an external API

This article describes how to use the Importer feature to import data from an external Application Programming Interface (API), and specifies the API format requirements.

Supported source data format

• The API must provide a response in JSON format
• The JSON response must contain an array of JSON objects, for example:

[
  { "name": "North Kivu", "code": "RD001" },
  { "name": "South Kivu", "code": "RD002" },
  { "name": "Ituri", "code": "RD003" }
]

• Nested objects are supported, therefore the following example would be okay:

{ "status": "OK",
  "data": 
    [  
      { "name": "North Kivu", "code": "RD001" },
      { "name": "South Kivu", "code": "RD002" }, 
      { "name": "Ituri", "code": "RD003" }
    ]
}

• Field names need to be consistent, therefore the following example would not work:

[
  { "location": "North Kivu" },
  { "loc": "South Kivu" },
  { "Location": "Ituri" }
]

• The API endpoint must support HTTP GET request

• If the API is not public, two types of Authorization headers are supported:

• Basic access authentication: a username and password in Base64 encoding

• Bearer token: a single secret token. ActivityInfo will send the Authorization header in the format “Bearer ” as part of the request

• Accessible through HTTPS

Importing data from API

To import data from API using the Importer feature, follow these steps:

1. Check if you meet the prerequisites:

• Have an ActivityInfo account
• Access to Form
• Appropriate permissions

2. Create a Form into which you are going to import the data. It is important to define the structure of the Form before importing the data.
   If you already have a Form, navigate to the Table view of it.
3. Select the “Import” tool from the Toolbar.

4. Click “From API.”

5. Set up the API import by filling out the following fields:

• API URL: paste the link here. Only secure protocols are supported (https).
• Select the authentication method, depending on the external service: “None” for public API for example; “Bearer token” or “Basic authentication.” Consult the documentation of the API that you’re using to determine what authentication method is supported.

6. Click “Continue” and wait for the data to load.
7. Select the data path in the Data preview window. If the API does not provide an array of objects directly, then you need to choose a path to the array to import.
   In this example, select “data” as the API query path.

If you have multiple data paths available in the drop-down list, then you need to determine which part of the response you want to import.
In this example, you can see that there are two arrays of objects (“provinces” and “changes”) in the API response:

{
  "status": "OK",
  "provinces": [
    {
      "name": "North Kivu",
      "code": "RD001"
    },
    {
      "name": "South Kivu",
      "code": "RD002"
    }
  ],
  "changes": [
    { 
      "date": "2025-01-01",
      "version": 1
    },
    {
      "date": "2025-03-02",
      "version": 2
    }
  ]
}

You cannot import both arrays at the same time, you need to choose one data path from the dropdown list.

7. Click “Continue” and wait for the Records to load.

8. Time to match columns and validate the Fields, by clicking through each highlighted column to resolve the issues. For more information, see Troubleshooting importer-related issues.
   In this step, you can use filters to limit the data you want to import.

Filtering is not available on Multiple reference field values and unmapped Fields. Target Field mapping is not supported.

Tip: You can set up a hidden Field with a default value in your Form to enable filtering on the unmapped source Field. This way the unmapped Field becomes a mapped Field.

9. After resolving the inconsistencies, click “Continue” in the upper right corner.
10. Users with “Manage import configurations” permission can choose to save this import configuration for repeated data imports, and share this with other Database users. Saved configurations are not run automatically.

The saved configuration option includes the following aspects:

• Import source (“From API” in this case)
• API URL, authorization, data path
• Matching of Fields, including constant values
• Filters, if applied
• Credentials are stored, if you use authentication in step. Although credentials are not visible to other users, be aware that anyone with the manage import configuration permission will be able to use the stored credentials to rerun the import in the future.

11. Review the “Import summary” overview:

• If everything is correct, proceed to the next step.
• If you need to start over, click “Cancel.”
• To go back to the matching of columns and validation of Fields part of the process, click “Back.”
• Toggle the “Save configuration” switch to save this import configuration, and click “Continue” in the pop-up window.

12. In case you are saving the configuration, type in a label for the saved configuration, then click “Save & Import records” in the upper right corner.

13. If you are not saving a custom configuration, click “Import records” in the upper right corner and wait for the updates to load.