Configure and Manage Outbound Web Services

Outbound Web Services exposes a straightforward REST API that enables external applications to access study data and metadata from elluminate datastores for analysis and reporting. Retrieval can target a single dataset, multiple datasets, or all datasets within a chosen data store, based on the caller’s study and datastore permissions.

The elluminate REST API offers five outbound endpoints. Endpoints return JSON for easy use with analytical tools or external applications. Full details of the endpoints are provided in the Endpoints section.

Access & Credentials

Per-user credentials handle authentication to the API and enforce the same study and datastore permissions as the user account. Each account accessing the API requires an Api Key and an Api Secret.

Generate Credentials

Log in as an Administrator.
Click the 9-dot icon and go to Platform Administration → User Management.
Click the Edit icon for the target user.
Open the Credentials tab and click Generate to create the Api Key / Api Secret. The credentials can be regenerated when needed.
Record the generated Api Key / Api Secret for the user account and deliver it securely to the user, team, or service that will call the API. The credentials can also be viewed in My Profile → API Credentials.

Pass Credentials in HTTP Header

Use the generated credentials for every request by including them in the HTTP headers as app-key and app-secret. In elluminate, they are generated and labeled as an Api Key and Api Secret, but the request must use the header names app-key and app-secret. Add these headers to whatever client makes the call to the elluminate API, whether it's a custom application, integration service, ETL pipeline, or script.

Include the following HTTP key-value pairs in the header:

app-key: <user account API key>
app-secret: <user account API secret>

Note: If the credentials are incorrect, the caller will get: 401 - Invalid API Credentials

Endpoints

Here are the available API endpoints. Click on any endpoint description below to expand it and view the details.

Important: A red asterisk * indicates a required field.

{url}/rest/v1/studies

Parameters:

(none)

Responses:

200 Successful Operation

401 Invalid API Credentials

404 Not Found

500 Internal Server Error

Example:
https://myurl.com/rest/v1/studies
{url}/rest/v1/datastores/{study}

Path Parameter:

{study}* Use the SchemaPrefix of the study.

Responses:

200 Successful Operation

401 Invalid API Credentials

404 Not Found

500 Internal Server Error

Example:
https://myurl.com/rest/v1/datastores/eCS_DS_001

{url}/rest/v1/datastores/{study}/domains?schemaName={datastore}

Example:
https://myurl.com/rest/v1/datastores/eCS_DS_001/domains?schemaName=eCS_DS_001_src

{url}/rest/v1/datastores/{study}/metadata?schemaName={datastore}&domainNames={domains}

Example:
https://myurl.com/rest/v1/datastores/eCS_DS_001/metadata?schemaName=eCS_DS_001_src&domainNames=AE,CE

{url}/rest/v1/datastores/{study}/data?schemaName={datastore}&domainName={domain}

Example:
https://myurl.com/rest/v1/datastores/eCS_DS_001/data?schemaName=eCS_DS_001&domainName=AE

Exploring & Testing

There are several tools that can be used to work with APIs, such as Postman, used for exploring, testing, and troubleshooting APIs.

This example shows how the app-key and the app-secret headers are applied in the HTTP headers section, using the values generated. See the Pass Credentials in HTTP Header section for more details.
This example sends the query parameters schemaName and domainNames to the endpoint that returns the field list for a given domain and study. Notice how when parameters are added, they are automatically appended to the URL endpoint.

Best Practices for Using the API

Create one service account per environment. Limit the account to read-only access for required studies and data stores. Generate an App-key and App-secret for the account, and store and rotate credentials in an approved secrets system.
Share keys through an approved process. Grant access using an enterprise password manager or secrets vault instead of sending raw values. If transmission is unavoidable, use a one-time, end-to-end encrypted method, set a short expiry, and log the access. Prohibit sharing via email, chat, tickets, code, or plain-text configurations.
Store the App-key and App-secret in an industry-standard secrets manager such as AWS Secrets Manager, Azure Key Vault, Google Secret Manager, or a CI/CD secrets store like GitLab CI/CD Variables or Azure DevOps Pipeline Variable Groups. Do not hard-code the generated values.
Rotate keys periodically and immediately on staff changes. Create new credentials, update pipelines and apps, verify successful calls, revoke old credentials, update the stored values, and redeploy pipelines/apps.
Validate the structure before pulling data. Call metadata endpoints to verify study access. Then, list the study’s available data stores using its SchemaPrefix. Select the correct store before requesting domains and data. Verify domain and field definitions, and compare the returned metadata with the expected schemas to identify any drift.
Minimize payloads and frequency. Request only required domains and columns, schedule extracts to match downstream needs, and avoid full-store pulls when a subset suffices. Prefer incremental transfers when business keys or timestamps allow downstream duplication.

Parameters:
	(none)
Responses:
	200	Successful Operation
	401	Invalid API Credentials
	404	Not Found
	500	Internal Server Error

Path Parameter:
{study}*		Use the SchemaPrefix of the study.
Responses:
	200	Successful Operation
	401	Invalid API Credentials
	404	Not Found
	500	Internal Server Error