Find participants via API

ENGAGE HELP CENTER

Finding participants via API

Before exporting data, you can search for specific participants by name, national ID, or other criteria.

Search Participants Endpoint

URL: GET https://engage-api.longenesis.com/search_org_participants/{org_slug}

Search Parameters

search_str: Search string to filter participants by any of the following fields:

Participant ID
National ID
Given name (first name)
Family name (last name)
Full name combinations (first + last, last + first)
Email address

limit: Maximum number of results to return (default: 50, max: 50)
offset: Number of results to skip for pagination (default: 0)
include_revoked: Include participants with revoked consent (default: true)

Example 1: Search for Participants by Name

import requests

# API configuration
AUTH_ENDPOINT = "https://engage-auth.longenesis.com/auth/realms/longenesis/protocol/openid-connect/token"
API_BASE_URL = "https://engage-api.longenesis.com"
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
ORG_SLUG = "your-organization"

# Get access token
auth_data = {
    "grant_type": "client_credentials",
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET
}

auth_response = requests.post(AUTH_ENDPOINT, data=auth_data)
access_token = auth_response.json()["access_token"]
headers = {"Authorization": f"Bearer {access_token}"}

# Search for participants by name
search_url = f"{API_BASE_URL}/search_org_participants/{ORG_SLUG}"
search_params = {"search_str": "Smith", "limit": 25}

search_response = requests.get(search_url, headers=headers, params=search_params)
search_data = search_response.json()

print(f"Found {search_data['total_count']} participants")
for person in search_data['persons']:
    print(f"ID: {person['person_id']}")
    if person['profile']:
        profile = person['profile']
        print(f"Name: {profile.get('given_name', '')} {profile.get('family_name', '')}")

Example 2: Search for Patient by National ID

# Search for patient by Latvian National ID
search_params = {"search_str": "010190-12345", "limit": 25}

search_response = requests.get(search_url, headers=headers, params=search_params)
search_data = search_response.json()

if search_data['total_count'] > 0:
    patient = search_data['persons'][0]
    print(f"Found patient: {patient['person_id']}")
    if patient['profile']:
        profile = patient['profile']
        print(f"Name: {profile.get('given_name', '')} {profile.get('family_name', '')}")
        print(f"National ID: {profile.get('national_id', '')}")
else:
    print("No patient found with that National ID")

Once you’ve identified the participants using the API, you can retrieve their data through the export endpoints. Depending on what you need, proceed to Export answers to download activity responses in XLSX, JSON, or PDF format, or to Export consents to get participant consent documents as PDFs.

Finding participants is an optional step.

You can export data for specific participants you’ve identified, or export all data within a given date range without filtering by participant.

← Read previous: SMS notifications