Mednet EDC REST API Overview

The Mednet EDC (Electronic Data Capture) REST API provides a single-point of access for reading data stored across iMednet data services. The API exposes data externally, such that a Sponsor, CRO, or other validated client can access the data using HTTP GET requests from a server or even web browser, provided the client can validate the required security credentials.

This level of data access allows iMednet users to read, store, analyze, and re-present data in a multitude of ways, including, but not limited to:

  • Export to a 3rd party reporting tool

  • Presenting data in a separate application, mobile app, or web site

  • Storing in a data warehouse

  • Compiling a custom audit trail

The Mednet EDC REST API returns all requests in JSON format (application/json). The JSON format (JavaScript Object Notation) provides flexibility and simplifies the task of manipulating data.

The documentation presented here will show you how to read and query data from the API based upon the object attributes.

Base URL

The address URL to access the API is the following:

https://edc.prod.imednetapi.com

To make requests, append the route of the endpoint to the base URL. For example, to make a request to the studies endpoint '/api/v1/edc/studies' use the following:

https://edc.prod.imednetapi.com/api/v1/edc/studies

Security and Validation

API keys should remain secure. Mednet does not recommend sharing keys or making them public. Publicly exposing your credentials can result in your account being compromised. Some implementation decisions can expose keys and should be avoided wherever possible (e.g. CORS).

Making a successful request requires authentication using request headers. Valid values for the request header attributes named x-api-key and x-imn-security-key are required to ensure secure access to your data. The content of your header might look something like the following:

{
    "x-api-key": "your-imednet-supplied-api-key",
    "x-imn-security-key": "your-imednet-supplied-security-key"
}

Example request using curl to request sites from STUDYKEY:

curl -X GET https://edc.prod.imednetapi.com/api/v1/edc/studies/STUDYKEY/sites -H 'x-api-key: XXXXXXXX' -H 'x-imn-security-key: XXX-XXX-XX-XXXXXX' -H 'Content-Type: application/json'

HTTP verbs

Verb Usage

GET

Used to retrieve a resource

POST

Used to insert data
Status code Usage

200 OK

The request completed successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

401 Unauthorized

The request was rejected related to security issue. The response body will include an error providing further information

403 Forbidden

The request was rejected related to security issue, likely an invalid studyKey. The response body will include an error providing further information.

404 Not Found

The request was rejected related to invalid resource issue. The response body will include an error providing further information

429 Too Many Requests

The request was rejected related to limit-exceeding requests. Please contact Mednet support for assistance

500 Internal server error

The request was rejected because of unknown issue. Please contact Mednet support for assistance

Resources

Filtering

iMednet REST API allows consumers to filter results by providing optional filtering criteria. However, filter criteria must meet specific syntax as below:

Attributes

Filter attribute must match (case sensitive) with end point response. Attributes vary for each endpoint, to see all attributes associated with each endpoint, view the specific endpoint documentation.

Table 1. Key Attributes
End point Key Attributes

Study

studyKey, studyType, studyName, dateCreated, dateModified

Site

siteId, siteName, siteEnrollmentStatus, dateCreated, dateModified

Form

formId, formKey, formName, formType, dateCreated, dateModified

Visit

intervalId, intervalName, intervalGroupId, intervalGroupName, dateCreated, dateModified

Record

intervalId, formId, formKey, siteId, recordId, parentRecordId, recordType, recordStatus, subjectKey, dateCreated, dateModified

Record Revision

recordRevisionId, recordId, recordOid, recordRevision, dataRevision, recordStatus, user, reasonForChange, dateCreated

Variable

variableId, variableType, variableName, dateCreated, dateModified, formId, formKey, formName, label

Coding

siteId, subjectId, formId, recordId, revision, variable, value, code, codedBy, reason, dictionaryName, dictionaryVersion, dateCoded

Operators

The following operators are supported:

Table 2. Operator
Operator Info

<

less then

⇐

less equal then

>

greater than

>=

greater equal than

==

equal

!=

not equal

Connectors

Connectors are used to join filter criteria together. The following connectors are supported:

Table 3. Connector
Connector Info

and

And condition

;

And condition

or

Or condition

,

Or condition

Date

Dates are returned in UTC. It is possible to search dates on any supported date attribute. Use UTC format when filtering for dates, except when searching for startDate, dueDate, endDate, and visitDate for the visits endpoint. For startDate, dueDate, endDate, and visitDate for the visits endpoint, use YYYY-MM-DD format.

Table 4. Date
Attribute Details

dateCreated

The timestamp when the entity was created

dateModified

The timestamp when the entity was last modified

startDate (specific to Visits endpoint)

Subject visit Start Date defined in interval visit window

endDate (specific to Visits endpoint)

Subject visit End Date defined in interval visit window

dueDate (specific to Visits endpoint)

Subject visit Due Date defined in interval visit window

visitDate (specific to Visits endpoint)

Subject visit Date defined in interval visit window
Table 5. Date format
Date format Info

YYYY-MM-DDTHH:MM:SSZ

UTC time

YYYY-MM-DDTHH:MM:SS-06:00

CST time, which is 6 hours behind UTC time

YYYY-MM-DD

Date without time, specific to startDate, dueDate, endDate, and visitDate for the visits endpoint

Filter Examples

Table 6. Filter Examples
Filter Value Expected Result

formId > 10

Return all forms with a Form ID greater than 10

formType == "SUBJECT"

Return all subject-related Forms

formId > 10;formType == "SUBJECT"

Return all subject-related Forms with a Form ID greater than 10

formId > 10 and formType == "SUBJECT"

formId > 10,formType == "SUBJECT"

Return all subject-related Forms or Forms with a Form ID greater than 10

formId > 10 or formType == "SUBJECT"

dateCreated>2000-11-05T08:00:00-06:00

Return all entities created after November 5, 2000 08:00:00 CST

dateCreated>2000-11-05T14:00:00Z

Return all entities created after November 5, 2000 14:00:00 UTC

visitDate<2019-03-19

Returns all entities where the visitDate occured before March 19, 2019

Filtering on Record Data

recordData is not a fixed structure, since each clinical form has its own structure determined by the study protocol and configured within the iMednet form designer. For this reason, a special request parameter, recordDataFilter, is available to indicate how to filter a set of records based upon values for questions.

This request parameter is optional, and is separate from the filter request parameter that operates on the structured record attributes such as recordId or formKey. In short, recordDataFilter is only used to query within the recordData attribute.

The recordDataFilter request parameter currently supports the use of the ";" (AND) or the "," (OR) connector, but not both at the same time.

Please refer to Filtering for more details about the filter query parameter.

Syntax

Record data filter criteria must meet specific syntax as below:

Table 7. Record data filter
Operator Info

<

less then

⇐

less equal then

>

greater than

>=

greater equal than

==

equal

!=

not equal

=~

contains (case insensitive, accepts regex, must escape special regex characters)

Separator

Each field in record data filter must be separated by ";" (AND) or "," (OR) value. Currently the API does not support the use of both. A bad request will be returned if both the ";" and "," connectors are used in the same recordDataFilter.

Table 8. Connector
Connector Info

;

And condition

,

Or condition

RecordDataFilter Examples

Table 9. Filter Examples
Filter Value Expected Result

AESER==Serious

Return all serious adverse events

AESER==Serious;GENDER==Male

Return all serious adverse events for male subjects

AESER==Bronchitis,AGE>65

Return all records where bronchitis occurred or if age is greater than sixty-five

AESER==bronch

Returns all serious adverse events that contain "bronch"

AESER==Bronchitis;GENDER==Male,AGE>=65

Returns 400 Bad Request

Pre-conditions

The criteria below must be met in order to perform a valid query:

Table 10. Criteria
Criteria Example

Semicolon (;) must be used to separate filter

number>1;name==John

White space is not allowed between key, operator, or value

number > 1 is invalid. number>1 is valid

Value must follow right after operator

name==John will search all name that match John. name=="John" will search all name that match "John"

Unique attribute is required

name==John;name!=John is invalid

dateCreated and dateModified are date in UTC format

dateCreated>2018 is invalid. dateCreated>2018-01-01T06:00:00Z is valid

All searches are case sensitive

name==John. This will search all name that has value of John.