Using a cURL API to Import Registry or Study Data

The Import cURL API allows Site Admins and Site Managers to efficiently import bulk data into a specific study or the Registry, enabling automated synchronization from third-party systems—without manual use of the Ripple Import Tool.

✅ Key Benefits

• • Bulk Data Import – Upload large datasets with a single command.

    • Automated & On-Demand – Run anytime; ideal for scheduled tasks.

  • System Integration – Connect Ripple with CRMs, CTMS, or databases.

  • Improved Data Harmonization – Keep participant data consistent across platforms.

🛠 What You Need Before You Start

1. Ripple Site URL – Your instance's API endpoint.
2. Study ID – The specific Study ID, or use "global" for Registry imports.
3. Update Option – Determines how the API handles existing participants.
4. Authorization Key – A valid API key (encoded username/password).
5. Formatted Excel File (.xlsx) – Must match the study or Registry's Data Dictionary.
6. Import cURL Command – A command formatted for your operating system.

Preparing the Excel File for Import

Use a study-specific or Registry Import template file, or modify an existing one.
The same rules as the Ripple Import Tool apply:

• Creating New Participants:

  • Required fields: First Name, Last Name

• Updating Existing Participants:

  • Required match: Global ID
    — OR —
    First Name, Last Name, and Birthday

• Formatting Requirements:

  • Column headers and values must match the study’s Data Dictionary.

  • Formatting is case-sensitive.

  • You may need to use a programming tool (e.g., Python, R, Excel macros) to prepare the file.

Update Options for Existing Participants

Option	Description
all	Updates all matching participants
nocontact	Skips updates to participants with contact info
noexisting	Only adds new participants, skips existing

Step-by-Step Instructions

1️⃣ Open Your Command Line Tool

• • Mac/Linux: Open Terminal

  • Windows: Open Command Prompt (cmd.exe)

2️⃣ Paste the Import cURL Command

Use the version formatted for your OS (see example below).

3️⃣ Replace the Placeholders

Placeholder	Replace With
RippleSiteURL	Your Ripple API URL
StudyId	Study ID or "global" for Registry
UpdateOption	One of: all, nocontact, noexisting
AuthorizationKey	Your encoded API key
LocationAndNameOfExcel.xlsx	Full file path to your .xlsx import file

4️⃣ Run the Command

Press Enter to execute.

5️⃣ Verify the Import in Ripple

Log into Ripple and confirm that the data was imported correctly.

Example: Importing Event Completion Data

Scenario:
A Study Data Analyst is importing Event Completion Data and Custom Variables from CTMS into the Ancillary A Study.
All participants already exist and should be updated.

• ✅ Use UpdateOption = all

• ✅ Ensure Excel file includes required fields

🖥 Mac/Linux cURL Example:

curl -X POST "https://RippleSiteURL/api/import/study/StudyId?updateOption=all" \
  -H "Authorization: Basic AuthorizationKey" \
  -F "file=@/Users/username/Documents/ImportFile.xlsx"

🖥 Windows cURL Example:

curl -X POST "https://RippleSiteURL/api/import/study/StudyId?updateOption=all" ^
  -H "Authorization: Basic AuthorizationKey" ^
  -F "file=@C:\Users\username\Documents\ImportFile.xlsx"