Consent PDF export

Engage Help Center

www.longenesis.com/engage

ENGAGE HELP CENTER

Consent PDF export

This guide explains how to download and save all consent PDFs from the Longenesis.Engage platform.

Overview

Retrieving signed consent documents requires three steps:
1. Authenticate with the Longenesis Auth service.
2. Retrieve a list of consent submissions (i.e., consents) made during the specified time period to obtain submission IDs.
3. Download individual consent PDFs using the retrieved submission IDs.

Prerequisites

- Valid Longenesis API credentials

Contact support@longenesis.com to get access credentials.

Applicable when using Python:
- Python 3.6 or higher
- requests library (pip install requests)

Complete Example

import requests

AUTH_ENDPOINT = "https://auth.longenesis.com/realms/curator-engage/protocol/openid-connect/token"
USERNAME = "<your username>"
PASSWORD = "<your password>"
CLIENT_ID = "<Longenesis issued client id>"
CLIENT_SECRET = "<Longenesis issued client id>"

ORG_SLUG = "<orgagization slug>"
PROJECT_SLUG = "<activity slug>"
ACTIVITY_SLUG = "<activity slug>"
DATE_FILTER_START = "2025-01-01"
DATE_FILTER_END = "2026-01-01"

access_token = requests.post(
    AUTH_ENDPOINT,
    data={
        "username": USERNAME,
        "password": PASSWORD,
        "grant_type": "password",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
).json()["access_token"]

# Get a list all submissions for the consent activity (up to 5000 in one response).
response = requests.get(
    f"https://engage-openapi.longenesis.com/v2/json_answers/{ORG_SLUG}",
    params={
        "activity_filter": ACTIVITY_SLUG,
        "date_filter": [DATE_FILTER_START, DATE_FILTER_END],
    },
    headers={"Authorization": f"Bearer {access_token}"},
)

for record in response.json()["records"]:
    submission_id = record["submission_id"]

    response2 = requests.get(
        f"https://engage-openapi.longenesis.com/pdf/{ORG_SLUG}/{PROJECT_SLUG}/{ACTIVITY_SLUG}/{submission_id}/admin_download",
        headers={"Authorization": f"Bearer {access_token}"},
    )
    with open(f"consent_file_{submission_id}.pdf", "wb") as f:
        f.write(response2.content)

Running the example

Before running the example script, you need to modify the following configuration parameters in the code:
- USERNAME: Your non-Gmail authentication username.
- PASSWORD: Your authentication password.
- CLIENT_ID: Longenesis issued client ID.
- CLIENT_SECRET: Longenesis issued client secret.
- ORG_SLUG: Slug of your Engage organisation.
- PROJECT_SLUG: The slug of the project where the consents are gathered.
- ACTIVITY_SLUG: The slug of the consent activity.
- DATE_FILTER_START: Beginning date for filtering submissions (YYYY-MM-DD format).
- DATE_FILTER_END: Ending date for filtering submissions (YYYY-MM-DD format).

The ORG_SLUG element can be found in the Engage section My organisation.

To find the ORG_SLUG element follow the below steps.
1. Log into the Engage platform.
2. Go to the section My organisation in Settings.
3. Navigate to the section Slug for your organisation invitation link.
4. Obtain the ORG_SLUG from the organisation link displayed. It is the last element of the link.

The PROJECT_SLUG element can be found in the Public sharing section of the Engage project.

To find the PROJECT_SLUG element follow the below steps.
1. Log into the Engage platform,
2. In the section Manage projects find the project where the consent activity is located.
3. Click on the three vertical dots on the card of the specific project and select Public sharing,
4. Obtain the activity slug from the very end of the Public link of the project.

The ACTIVITY_SLUG element can be found in the Public sharing section of the Engage activity.

To find the ENGAGE_ACTIVITY_SLUG element follow the below steps.
1. Log into the Engage platform,
2. Click the button View activities on the Engage project where the consent activity is located,
3. Click on the three vertical dots on the card of the specific activity and select Public sharing,
4. Obtain the activity slug from the very end of the Public link of the activity.

Date filtering

The DATE_FILTER_START and DATE_FILTER_END parameters allow you to narrow down the returned submission list to a specific time range.
Important notes about date filtering:
- Dates must be in YYYY-MM-DD format (e.g., "2025-01-31").
- Both start and end dates are required when using date filtering.
- The filter includes records from the start date but excludes records from the end date.

Common filtering scenarios:
- For a specific date range: "2025-01-01" to "2025-02-01" (January 1-31)
- For yesterday's data: If today is "2025-01-15", use "2025-01-14" to "2025-01-15"
- For last month's data: If current month is January 2025, use "2024-12-01" to "2025-01-01"
- For a single day: To get only Jan 1st data, use "2025-01-01" to "2025-01-02"

Note on dates: These dates cannot be blank. If you don't want to filter by date, you need to modify the code to remove the date filter parameters from the API request URL.

Note on sorting: Returned list is ordered by created_at field. When a patient updates or revokes their consent, the updated_at field is updated. To sort returned list by updated_at, pass parameter order_by_updated_at=true. This will enable sorting and filtering by updated_at.

Endpoint schema and interactive documentation can be found at Longenesis Engage API.

Our team is ready to provide you assistance in any of the steps and would gladly guide you through the process.

Do not hesitate to contact us via support@longenesis.com if you have any questions or any help is required.

← Read previous: Engage API for data export