Engage API for data export

Engage Help Center

www.longenesis.com/engage

ENGAGE HELP CENTER

This section will be your guide on how to export data from the Engage platform with help of Engage API.

Export participants' responses with API

Longenesis.Engage provides API for eligible clients. Endpoints to export participants' responses in JSON and Excel formats are available. Check the python code sample provided below to see how to obtain the token, as well as download the export file.
Additionally, interactive API documentation is available here: https://engage-openapi.longenesis.com/docs.

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>"

ENGAGE_ORG_SLUG = "<orgagization slug>"
ENGAGE_ACTIVITY_SLUG = "<activity slug>"

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"]

response = requests.get(
    f"https://engage-openapi.longenesis.com/v2/xlsx_answers/{ENGAGE_ORG_SLUG}",
    params={
        "activity_filter": ENGAGE_ACTIVITY_SLUG,
        "date_filter": ["2022-01-01", "2023-01-31"],
    },
    headers={"Authorization": f"Bearer {access_token}"},
)
with open("report_file.xlsx", "wb") as f:
    f.write(response.content)

Note, it is possible to export up to 5000 activity entries at one time.

In order to export the total activity results where the number of submissions exceed 5000, apply the parameter offset to define the number of entry with which to start the export. 5000 entries starting with the one indicated in the offset parameter will be exported. Below is an example how the offset parameter has been applied to export 20000 entries in four separate export requests.

/v2/xlsx_answers/ENGAGE_ORG_SLUG?offset=0&limit=5000
/v2/xlsx_answers/ENGAGE_ORG_SLUG?offset=5000&limit=5000
/v2/xlsx_answers/ENGAGE_ORG_SLUG?offset=10000&limit=5000
/v2/xlsx_answers/ENGAGE_ORG_SLUG?offset=15000&limit=5000

Filtering data by date
Please note how date_filter parameter here is a list. If you use curl-like download tool, the download link will look the following way:

https://engage-openapi.longenesis.com/v2/xlsx_answers/ENGAGE_ORG_SLUG?activity_filter=ENGAGE_ACTIVITY_SLUG&date_filter=2022-01-01&date_filter=2023-01-31

Notice how date_filter appears twice in the URL. This is ok. The multiple date_filter values will get combined into a list on the API server. Please note that you can pass multiple intervals using date_filter, for instance, ...&date_filter=START1&date_filter=END1&date_filter=START2&date_filter=END2&, where START1, END1, START2, END2 are successive timestamps with timezone information.

Please consult https://docs.python.org/3/library/datetime.html#datetime.datetime.fromisoformat on how to construct valid ISO 8601 timestamps.

Filtering data by participants
The person_filter parameter allows you to limit the exported information to specific persons.

The download link will look the following way:

https://engage-openapi.longenesis.com/v2/xlsx_answers/ENGAGE_ORG_SLUG?activity_filter=ENGAGE_ACTIVITY_SLUG&person_filter=P-123456&person_filter=P-654321

How to run the sample script

We provide the sample script in the python programming language. However, the workflow illustrated here will be the same in any other language.
To run the sample script you will need credentials (username, password, client_id, client_secret are issued by Longenesis) and the ID of the activity (you can find it in the Engage platform).
Apart from having Python installed, you will also need the popular requests library to make API calls and optionally a virtual environment too.
Assuming you have saved the sample code in a file my_sample_script.py and have set the credentials and activity ID correctly, you can create the virtual environment, run the script and have your export file by running the following commands in terminal:

python3 -m venv venv
source venv/bin/activate
pip install requests
python3 my_sample_script.py

A new file report_file.xlsx should now appear in the same folder.

Export participants' response PDFs with API

Participants submissions converted to PDF can be exported from endpoint /pdf/{org_slug}/{project_slug}/{activity_slug}/{submission_id}/admin_download
The submission_id is available in the response from Engage API endpoint /v2/json_answers/{org_slug} - the endpoint you would normally use to get a list of submissions in your Organization's activities.

The suggested workflow
1. Use endpoint /v2/json_answers/{org_slug} to get a list of submissions.
2. Use endpoint /pdf/{org_slug}/{project_slug}/{activity_slug}/{submission_id}/admin_download to get PDF version for each submission.
Please refer to the Engage API documentation at https://engage-openapi.longenesis.com/docs to learn more about available endpoints.

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>"

ENGAGE_ORG_SLUG = "<orgagization slug>"
ENGAGE_PROJECT_SLUG = "<project slug>"
ENGAGE_ACTIVITY_SLUG = "<activity slug>"
ENGAGE_SUBMISSION_ID = 12345600  # refer to the json with exported submissions


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"]

response = requests.get(
    f"/pdf/{ENGAGE_ORG_SLUG}/{ENGAGE_PROJECT_SLUG}/{ENGAGE_ACTIVITY_SLUG}/{ENGAGE_SUBMISSION_ID}/admin_download",
    params={
        "lang": "en",  # or any other language that is supported by Engage
        "include_sections": ["report", "pinned_questions", "calculated_answers", "response_alerts", "localized_answers"],
    },
    headers={"Authorization": f"Bearer {access_token}"},
)
with open("report_document.pdf", "wb") as f:
    f.write(response.content)

About include_sections parameter
The include_sections parameter regulates which report sections are included in the PDF. Normally all sections are included for admin PDFs, but only "report" and "localized_answers" for participant PDF. Using API, you have choice regarding what sections to include in the resulting PDF document.

Full API documentation is available here.