1. Checkbox
  2. Guides
  3. Use Cases

Sync Third Party Data into a Checkbox Database

In this Article

Learn how to use the Scheduled Assessment Creation feature and populateDatabase() function to fetch data from third-party APIs and store it in a Checkbox database.

Step-by-Step Instructions

Before You Start

  • Have a JavaScript integration snippet ready (See JavaScript Block guide).
  • Ensure your Checkbox database has the appropriate columns.
  • Basic proficiency in JavaScript and Checkbox is required. Speak to Checkbox Support if you require Professional Services.

Implementation Steps

1. Create a Checkbox database with the appropriate columns

image.png

2. Store the Checkbox database UUID found in the URL to be used in the JavaScript snippet

image 1.png

3. Configure the JavaScript snippet to format the data, and call the populateDatabase() function.

You will need to make two additions to your existing JavaScript integration snippet.

    • Convert the 3rd party API data into an array of objects structure. This may be the trickiest part of the set-up since this formatting is custom to each 3rd party. The keys in each object must match the field/column names in the target Checkbox database, or records will not be updated. (Ex: “Currency” and “Exchange rate” must be names of columns in your Checkbox database).

// Example array of objects data structure
const data = [
{
"Currency": "AED",
"Exchange rate": 3.6725,
},
{
"Currency": "AFN",
"Exchange rate": 73.1439,
},
{
"Currency": "ALL",
"Exchange rate": 94.4244,
},
];

 

  • Add a call to the populateDatabase() function so you can take the output of the third party API call and use it as an input into the Checkbox database. Here are the parameters:
Parameter Type Description
databaseId UUID The UUID of the database where data will be inserted. This can be found in the URL of the target database.
data array An array of records that will be inserted into the database.
uniqueIdentifier (optional) string The key used for upserting records. Default upserts all entries including duplicates.
isTestData (optional) boolean If true, the data will be inserted into the test database instead of the production database. Default is false.

 

Once you're done your Javascript should look something like:

// Configure options //
const databaseId = `3946c8da-c101-47eb-91d0-3a48231b300a`; // Replace with your UUID
const uniqueIdentifier = 'Currency'; // Optional
const isTestData = false; // Optional

// Fetch exchange rates and update the database
const API_KEY = '1caa075639009848f0309ee2'; // https://app.exchangerate-api.com/
const endpoint = `https://v6.exchangerate-api.com/v6/${API_KEY}/latest/USD`;
api.makeRequest({
method: 'GET',
url: endpoint,
}).then((response) => {

// Convert API response into the correct format (an array of objects)
const conversionRatesArray = Object.entries(
response.data.conversion_rates
).map(([currency, rate]) => ({
'Currency': currency,
'Exchange Rate': rate,
}));

// Populate database with the formatted exchange rates
const result = api.populateDatabase({
databaseId: databaseId,
data: conversionRatesArray,
uniqueIdentifier: uniqueIdentifier, // Optional
isTestData: isTestData, //Optional

});
}).catch((error) => {
// Handle errors
console.error(error);
});

 

4. Create a new App and upload the script in a JavaScript block.

image 2.png

5. Toggle on “Enabled scheduled assessment creation” under the Scheduled Assessment Creation feature in the Start block. Configure as necessary.

image 3.png

6. Publish the workflow once you have confirmed the Checkbox database sync in preview.

Common Errors & Troubleshooting

Data is Not Being Inserted

✅ Ensure field names match exactly with those in the Checkbox database. If they don’t, records will not be upserted.

✅ Check the API response format—the structure must align with the expected database schema.

API Request Fails

✅ Verify the endpoint URL is correct and accessible.

✅ Ensure the API method (GET, POST, etc.) matches the external API’s requirements.

✅ If authentication is required, include necessary headers (e.g., API key, token) in api.makeRequest().

Data is Inserted into the Wrong Database

✅ Confirm that you are using the correct databaseId.

✅ If using test data, ensure isTestData: true is correctly set to avoid affecting production data.

If you encounter issues or need professional services, please contact Checkbox Support.