Create participants and submission with API

Engage Help Center

www.longenesis.com/engage

ENGAGE HELP CENTER

Create participants and submissions with API

Learn how to register participants or enter information about authorised participants using API.

Prerequisites for using the Engage API

Before using the Engage API, ensure you have the following authentication credentials:
1. USERNAME:
To obtain a username, register on the Engage platform using a non-Gmail email address. Your username will be the email address you provided during account creation.
Gmail accounts are not supported for API authentication because verification of Gmail credentials requires an interactive browser session.

2. PASSWORD:
The password associated with your Engage account.

3. CLIENT_ID:
Typically, this matches your organization's slug in Engage. If you're unsure, contact Longenesis Support at support@longenesis.com for confirmation.

4. CLIENT_SECRET:
A unique secret issued by Longenesis and sent to you via a secure channel.

Setting up permissions to import participants or submissions

Your account must have administrator rights in the Engage organization to import data via the Engage API.
At a minimum, you need Manage Submissions and Manage Participants permissions at the organization level or for the specific project.

Read more about Permission management or contact Longenesis Support at support@longenesis.com to obtain the required permissions.

Import request

To import data you need to perform two requests:
1. A POST request to Longenesis Auth service (https://auth.longenesis.com/realms/curator-engage/protocol/openid-connect/token). For this you need the credentials. The Auth service responds with the auth token.
2. A POST request to Engage API (https://engage-openapi.longenesis.com/submissions/{ENGAGE_ORG_SLUG}/bulk_post). For this you will need the auth token obtained in the first step and the actual json data you want to import.

We provide two endpoints for data importing:
- /submissions/{org_slug}/bulk_post
- /submissions/{org_slug}/bulk_upload

The only difference is that the /bulk_post accepts json data in the request body, while /bulk_upload accepts uploaded json file. Use one or both depending on your circumstances.
Schemas for requests and responses are available in our interactive API documentation here https://engage-openapi.longenesis.com/docs#/Submissions
You can perform data importing in the programming language of your choice or even manually (with Postman, Insomnia, etc). For your convenience, we provide a verified example in Python below.

import requests

AUTH_ENDPOINT = (
    "https://auth.longenesis.com/realms/curator-engage/protocol/openid-connect/token"
)
USERNAME = "<engage login email>"  # use non-gmail account with sufficient permissions
PASSWORD = "<engage login password>"
CLIENT_ID = "<Longenesis issued client id>"
CLIENT_SECRET = "<Longenesis issued secret>"

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

data_for_import = {
    "records": [
        {
            "participant": {
                "participant_id": "string",  # conditionally optional
                "national_id": "123456-11111",  # conditionally optional
                "email": "participant@longenesis.com",  # conditionally optional
                "given_name": "John",  # optional
                "family_name": "Doe",  # optional
                "phone": "+371 22222222",  # optional
                "update_profile": true,  # optional
                "text": "Imported via API",  # optional. A comment field that's displayed on patient's profile
            },
            "submission": {
                "activity_slug": "abcdef",
                "partner_item_id": "d-patient-1",  # optional
                "created_at": "2024-09-01 10:100", # optional
                "answers": {  # the question IDs as in your Engage survey
                    "question1": "abc",
                    "question2": "abc",
                    "question3": "abc"
                },
            },
        }
    ]
}


response = requests.post(
    f"https://engage-openapi.longenesis.com/submissions/{ENGAGE_ORG_SLUG}/bulk_post",
    json=data_for_import,
    headers={"Authorization": f"Bearer {access_token}"},
)
print(response.status_code)
print(response.json())

The data is imported in participant and submission pairs. A participant is identified by either a participant_id, national_id or email. At least one of these must be present.
Partners are encouraged to use the same participant IDs as in their systems. This allows searching in Engage by known IDs. If a participant_id is not provided, Engage will generate a unique ID in the form of `P-xxxxxx`.
The partner_item_id in submission object is meant to map the Submission in Engage with the same information entity in the Partner system. If multiple submissions with the same partner_item_id are imported, Engage will create new versions for that submission.
The created_at in submission object is a datetime field to store the suggested creation timestamp. Partners can use the timestamp from their systems or any timestamp that is significant for the particular submission. Engage will store the submission with the provided created_at timestamp. If created_at is not provided, Engage will use current timestamp.

Full API documentation is available here.

← Read previous: Engage API for data export