Using the cURL API to Export Registry or Study Data

Export cURL API for Bulk Data Export

The Export cURL API enables Site Admins and Site Managers to efficiently export data from the Registry or a specific study without manually using the Ripple Export Tool. This method allows for automated, on-demand data extraction and facilitates seamless integration with third-party systems.

Key Benefits of Using the Export cURL API

✅ Bulk Data Export – Extract large datasets without manual intervention.
✅ Automated & On-Demand – Run the command anytime to get up-to-date data.
✅ System Integration – Easily transform and import data into third-party platforms.
✅ Improved Data Harmonization – Ensure consistency across multiple systems.

How to Use the Export cURL API

1. 1. Check Permissions

      • Ensure you are a Site Admin or Site Manager with export permissions.

   2. Prepare the cURL Command

      • Define the Ripple Site URL, authorization key, export type, timezone, and variables to export.

   3. Run the Command

      • Execute the cURL command in a terminal or command-line interface.

   4. Process the Exported Data

      • Save the output in a CSV or Excel file.
      • Transform the data as needed for integration into a third-party system.

   5. Schedule Regular Exports (Optional)

• • • Use task schedulers (e.g., cron jobs, Windows Task Scheduler) to automate data extraction.

What You Need Before You Start Exporting Data with cURL

Before executing the Export cURL Command, ensure you have the following details ready:

✅ 1. Ripple Site URL

• • • The URL of your Ripple instance where the data is stored.
    • Example: https://your-ripple-site.ripplescience.org

✅ 2. Authorization Key

• • • A unique API key that authenticates your request.

    • This ensures only authorized users can export data.

✅ 3. Study ID (if exporting from a specific study)

• • • The unique ID of the study you are exporting data from.

    • Found in the study URL within Ripple.

✅ 4. Time Zone

• • • Specifies the timezone for event and date-related data.

    • Example: "America/Chicago"

✅ 5. Variables to Export

• • • A list of variable names that match the Data Dictionary or Export Page in Ripple.

    • Example: globalID, firstName, lastName, birthday, race, ethnicity, status

✅ 6. Output Excel File Name

• • • The name of the CSV or Excel file where the exported data will be saved.

    • Example: "StudyDataExport.csv"

✅ 7. Export cURL Command

• • • A properly formatted cURL command that includes all the above details.

Example:

"https://your-ripple-site.ripplescience.org/api/export""Authorization: Bearer YOUR_AUTH_KEY""Content-Type: application/json"'{ "export-Type": "STUDY_ID", "timezone": "America/Chicago", "variables": [ "globalID", "firstName", "lastName", "birthday", "race", "ethnicity", "status" ], "fileName": "StudyDataExport.csv" }'

 

Exporting Data Using cURL: Mac & Windows Users

This guide provides step-by-step instructions on using the Export cURL Command to extract data from Ripple Science, whether you're using Mac or Windows.

📌 Export cURL Command Format (Mac Users & Window Users)

🔹 Step-by-Step Instructions

1️⃣ Open the Terminal or Command Prompt

• • • Mac Users → Open Terminal

    • Windows Users → Open Command Prompt (cmd.exe)

2️⃣ Paste the Export cURL Command

Copy and paste the appropriate command into your terminal.

3️⃣ Replace Placeholders with Actual Values

✅ RippleSiteURL → Enter the URL of your Ripple instance.
✅ AuthorizationKey → Replace with your actual API key.
✅ StudyId → Enter the Study ID (or use "global" for Registry export).

✅ TimeZone → Update to your correct timezone (e.g., "America/New_York").
✅ Variable Names → List the exact variable names (matching the Data Dictionary).
✅ Exported Excel File Name → Choose a name for the output CSV file.

🔹 Example of a Completed cURL Command

curl 'https://supportplayground.ripplescience.org/v1/export' \ --header 'Authorization: Basic abc12345xyz67890' \ --data-raw 'export-type=12345-study&export-timezone=America/Chicago&globalID=on&firstName=on&lastName=on&birthday=on' > StudyDataExport.csv

🔹 Verifying Your Export

1. Check your Downloads or specified directory for StudyDataExport.csv.
2. Open the file in Excel to verify the exported data.

Tailoring Your Export cURL Command for Ripple Science

When constructing an Export cURL Command, it's crucial to ensure that variable names are formatted correctly and special characters are properly encoded.

📌 Key Considerations for Variable Names

Spaces & Special Characters

• Spaces are replaced with underscores (_).
• Custom Variables must include "cv." before the variable name.
  • Example: "Potential Eligibility" → cv.potential_eligibility

Pre-Set Ripple Variable Name Exceptions

Tables can't be imported directly. Please insert an image of your table which can be found here.

Variable Name in Ripple Export cURL Command Format

📌 Example: Exporting Participant Data

A Data Analyst needs a report containing:

• First Name, Last Name, Global ID, Custom ID, Status, Sex, Race

• From the Ancillary A Study

• In the America/Chicago timezone

✅ cURL Command (Mac/Linux)

curl 'https://supportplayground.ripplescience.org/v1/export' \ --header 'Authorization: Basic ZXhhbXBsZS51c2VyQHJpcHBsZXNjaWVuY2UuY29tOnN1cGVyc2VjcmV0cGFzc3dvcmQxMjMK' \ --data-raw 'export-type=bdHZw2JPpZxvcY6Qv&export-timezone=America%2FChicago&firstName=on&lastName=on&globalId=on&customId=on&statusId=on&sex=on&race=on' > StudyDataExport.csv

✅ cURL Command (Windows)

curl "https://supportplayground.ripplescience.org/v1/export" ^ --header "Authorization: Basic ZXhhbXBsZS51c2VyQHJpcHBsZXNjaWVuY2UuY29tOnN1cGVyc2VjcmV0cGFzc3dvcmQxMjMK" ^ --data-raw "export-type=bdHZw2JPpZxvcY6Qv&export-timezone=America%2FChicago&firstName=on&lastName=on&globalId=on&customId=on&statusId=on&sex=on&race=on" > StudyDataExport.csv

📌 Steps to Customize Your Export cURL Command

1️⃣ Choose the Correct cURL Format

• • Mac/Linux → Use single quotes (')

  • Windows → Use double quotes ("), and line continuation (^)

2️⃣ Update the Ripple Site URL

• • Replace https://supportplayground.ripplescience.org with your actual Ripple site URL

3️⃣ Replace the Authorization Key

• • Update "Authorization: Basic YOUR_AUTH_KEY" with your actual API key

4️⃣ Enter the Correct Study ID

• • If exporting from a study, enter the Study ID

  • If exporting from the Registry, use "global"

5️⃣ Adjust the Time Zone

• • Modify "America%2FChicago" if needed (e.g., "America%2FNew_York", "UTC")

6️⃣ Specify the Variables to Export

• • Match variable names exactly as listed in the Ripple Data Dictionary

  • For custom variables, add cv. before the name (e.g., cv.potential_eligibility)

7️⃣ Set the Output File Name

• • Change StudyDataExport.csv to your desired file name