Jack Imaging

Developer API Documentation

Usage notes

The Jack Imaging Developer API consists of two parts. They are:

The Jack Imaging Authorization API
The Jack Imaging Authorization API implements the three legged OAuth2 authorization code grant workflow to authorize your application for access to the user's content. We recommend using an OAuth2 client library, though implementing your own auth provider is possible as well.
The Jack Imaging Content API
The Jack Imaging Content API is a RESTful API that allows for your application to interact with the user's content on Jack Imaging.

All Jack Imaging API requests must be sent over HTTPS.

Jack Imaging Authorization API

You must first register a client with Jack Imaging. Then follow the steps below to get started.

Step 1. Present the Jack Imaging OAuth Dialog

Your client should send a GET request to fetch the OAuth login dialog.

GET https://jackimaging.com/oauth/authenticate?
   client_id=YOUR_REGISTER_CLIENT_ID
   &response_type=code
   &redirect_uri=YOUR_REGISTERED_CLIENT_REDIRECT_URI
   &scope=basic
   &state=SOME_ARBITRARY_BUT_UNIQUE_STRING

The value for "response_type" must be code and the value for "scope" must be basic. No other values are currently permissible.

For maximum security the state should be a string that is recoverable by your client. Jack Imaging will eventually return an access token accompanied by the initially requested state; the client should verify that the states match. If they don't match, an unauthorized third party is sending you a fake access token! Possible ways of recovering the state include storing the request and its state in the client's server database, or cryptographically hashing the client_id, sending it as state, un-hashing the received state, and comparing it with the known client_id.

The redirect_uri specified in the request must match the redirect_uri registered for the specified client_id. If the client_id is not found, or the redirect_uri does not match, the user sees a web page with an error. The user is not redirected to the client's registered redirect_uri for this kind of error for security reasons.

All other errors for this API request will redirect the user to the redirect_uri with a 400: Bad request message with parameters error_description and error. For example if response_type is invalid the response will be this URL:

https://yourdomain.com/your_registered_client_redirect_uri?error_description=response_type%20is%20not%20code&error=unsupported_response_type

Your client should interpret this error message and display something informative for the user.

Step 2. The user is prompted to authorize your application

Your client's user sees a login screen prompting them to enter their account name and password. Once the form is submitted, Jack Imaging authenticates the login information. (Since this is the three-legged OAuth implementation, your client thus never has access to the user's Jack Imaging login information.) After the user login information is authenticated, Jack Imaging redirects the user's agent (web browser) to the client's redirect_uri with an authorization code.

Step 3. The client's redirect_uri receives an authorization code

If the user successfully authenticates and thus authorizes your client, the user's agent will be redirected to

GET REDIRECT_URI?
    scope=THE_INITIALLY_SPECIFIED_SCOPE
    state=YOUR_STATE_VALUE
    &code=AUTHORIZATION_CODE

After receiving this message the client must exchange the authorization code for an access token.

If the user did not authorize your client or the user's login information did not authenticate correctly, the user's agent will be redirected to

GET REDIRECT_URI?
    error=access_denied
    &error_description=could%20not%20authenticate%20user

Step 4. Exchange the authorization code for an access token

Once the client's redirect_uri receives an authorization code, the server receiving the code can exchange the code for a user access token. To do so, send a POST request containing the following parameters:

client_id: the registered client id
client_secret: the registered client secret
grant_type: authorization_code
code: THE_AUTH_CODE
redirect_uri: the same redirect_uri specified in the initial GET request and registered for the specified client_id

Here is an example of a request to exchange an authorization code for an access token:

POST /oauth/token HTTP/1.1
   Host: jackimaging.com
   Content-Type: application/x-www-form-urlencoded;charset=UTF-8

   grant_type=authorization_code
   &code=AUTHORIZATION_CODE
   &redirect_uri=YOUR_REGISTERED_CLIENT_REDIRECT_URI
   &client_id=YOUR_REGISTERED_CLIENT_ID
   &client_secret=YOUR_REGISTERED_CLIENT_SECRET

Jack Imaging receives this request and validates the information in it. If the authorization code is valid, then Jack Imaging will send a POST to the redirect_uri with the following parameters:

{
   "access_token":ACCESS_TOKEN,
   "token_type":"bearer",
   "expires_in":3600,
   "state":THE_INITIAL_STATE
}

At this point the client or its server needs to verify that the state in Jack Imaging's response matches the initially specified state. This verifies that the response is in fact from Jack Imaging. Store the access_token and use it with all subsequent API requests.

Step 5. Make requests to the Jack Imaging Content API

Once the client has a user access token, it may initiate calls to the Jack Imaging Content API on the user's behalf.

Jack Imaging Content API

Each valid API request specifies an endpoint and required arguments. For example, requesting a list of the user's DICOM images as a GET request would look like this:

https://jackimaging.com/api/dicom?access_token=ACCESS_TOKEN&action=list

Success responses will vary depending on the API request; see each request's documentation below. However all success responses will contain a JSON object of the form:

{
    'status':'success',
    'results':an_array_of_results
    'count':number_of_elements_in_array_of_results
}

Error responses will contain a JSON object of the form:

{
    'status':'error',
    'explanation':'an error message'
}

User profile

List profile information

endpoint	/api/me
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes

success response:

{
    'status':'success',
    'count':1,
    'results':[
        {
            "displayName": "Foo Bar", 
            "email": "foo.bar@gmail.com", 
            "firstName": "Foo", 
            "identifier": "nephosity/foo.bar@gmail.com", 
            "lastName": "Bar", 
            "phone": null
        }
    ]
}

DICOM images

The API lets your client list, upload, download, view, and remove a user's medical images.

DICOM images are organized hierarchically. You should have a basic understanding of this hierarchy in order to effectively use the API.

Studies: At the top level, DICOM images are organized into studies. Studies represent a collection of images which are created during a single patient scan. A layman's analogy to studies, would be the concept of albums in iPhotos.

Series: A study contains one or more series. A series is a collection of images which represent a particular view of the patient for the scan. For example, an MRI may have a series from each of the axial, coronal, and saggital views. A layman's analogy to series, would be the each item in an iPhoto album.

Instances: A series contains one or more instances. An instance correlates to a single file on the file system. A layman's analogy to instances, would be either the picture or video in an iPhoto album.

Frames An instance has one or more frames. Most modalities (e.g. X-rays, MRI, CT) use a single frame per instance, while some modalities (e.g. ultrasounds, angiograms) are multi-frame, i.e. use multiple frames per instance. The former is analogous to a picture, while the latter is analogous to a video.

List DICOM series

List previously uploaded dicom series.

endpoint	/api/dicom
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	list	Yes
public	0 (default, false) or 1 (true)	No

The public argument, if true, retrieves publically available dicom series instead of the user's dicom series.

success response:

{
   "status": "success", 
   "count": 2, 
   "results": [{'organizations': ['nephosity'], 
                'original dicom size': -1, 
                'processed size': -1, 
                'series date': '2012-12-10', 
                'study date': '2012-12-10', 
                'seriesuid': '1.2.826.0.1.3680043.9.1433.377223384.347598', 
                'studyuid': '1.2.826.0.1.3680043.9.1433.377223362.452042', 
                'study title': 'MR ABDOMEN', 
                'series title': 'SUB_S11-S7_1', 
                'study description': 'M4183 Abd w/', 
                'series description': 'ProtocolName', 
                'modality': 'MR', 
                'patient dob': '2012-12-14'}, 
               {'organizations': ['97f18286-fd8f-11e3-8169-12313f04e5e2'], 
                'original dicom size': -1, 
                'processed size': -1, 
                'series date': '2006-12-01', 
                'study date': '2006-12-01', 
                'seriesuid': '1.3.46.670589.11.0.0.11.4.2.0.8743.5.5396.2006120114314125550', 
                'studyuid': '2.16.840.1.113669.632.20.1211.10000357775', 
                'study title': 'BRAINIX', 'series title': 'T2W-FE-EPI', 
                'study description': 'IRM c\xe9r\xe9brale, neuro-cr\xe2ne', 
                'series description': 'T2W-FE-EPI SENSE', 
                'modality': 'MR', 
                'patient dob': '1949-03-01'}
              ]
}

List and download individual DICOM series files

Once the client has the studyuid and seriesuid, it can request a list of the files in the series.

endpoint	/api/dicom
Parameter	Value	Required?
access_token	A valid access token, obtainable with the Authorization API	Yes
action	list_files	Yes
studyuid	a studyuid, obtainable with the list action	Yes
seriesuid	a seriesuid, obtainable with the list action	Yes
imageuid	the imageuid, obtainable with the list action. Indicates that this is a multiframe DICOM.	Only if present in the series info obtained with the list action

The response will contain a list of URLs, each of which corresponds to a file. Each URL can be used to download the file. Note: For the URLs to work, a valid access token must be appended as a parameter.

success response:

{
    "status": "success",
    "count": 22,
    "results": [
        "https://jackimaging.com/api/dicom?action=download_file&hashpath=feef8a8c91c734e21e8887fae3b553f3bf68b727a4e844391ba33b3a7359f464",
        "https://jackimaging.com/api/dicom?action=download_file&hashpath=7ba59822864e992debca641601b31836f1c4b7cf87686fe24297a522dfc7ce54",
        ...
    ]
}

Bundle all files in a series

You can download the series as a bundle (a single file containing all the images). To do so, first issue a request to create a bundle. Currently, the bundle is a gzipped tarball (.tgz format)

endpoint	/api/dicom
Parameter	Value	Required?
access_token	A valid access token, obtainable with the Authorization API	Yes
studyuid	a studyuid, obtainable with the list action	Yes
seriesuid	a seriesuid, obtainable with the list action	Yes
imageuid	the imageuid, obtainable with the list action. Indicates that this is a multiframe DICOM.	yes, if present in the results of the list action
action	bundle	Yes

Upon successful completion of this request the client will receive a response that provides a URL which can be used to download the bundle. Note: an access_token parameter with a valid access token argument must be appended to the URL in order to download the bundle. The bundle is a gzipped tarfile and will have the .tgz file extension.

success response:

{
    "status": "success",
    "count": 1,
    "results": [
        "https://jackimaging.com/api/dicom?action=download_bundle?parameters=arguments"
    ]
}

Downloading the bundle

The url provided by the results of the bundle action, if successful, will respond with an HTTP 200 code, along with the contents of the file in the response body. If something goes wrong, then another HTTP error code will be issued, and the response body will be an explanation of the error

Upload DICOM images

This documentation is for uploading DICOM images. To upload other files such as jpgs or pdfs, see the case API documentation.

DICOM file upload consists of three steps because the Jack Imaging API is stateless. (The steps will define the state of the upload.) When implementing DICOM file upload in your client, be sure to execute the steps in order. Each step must finish before the next one begins.

Request an upload ID
Upload each file using the upload ID
Indicate all file uploads for this upload ID are done

Request an upload ID

endpoint	/api/dicom
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	upload	Yes
step	request_upload_id	Yes
requested_id	a string	No

The requested ID may or may not be granted depending on whether it already exists or not.

success response:

{
    "status":"success",
    "count":1,
    "results":[
        {
            "upload id": {
                "requested":$REQUESTED_ID,
                "assigned":$ASSIGNED_ID
            }
        }
    ]
}

Upload each file

Issue one upload request for each file to be uploaded.

endpoint	/api/dicom
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	upload	Yes
step	upload_file	Yes
upload_id	upload ID	Yes
file_name	name to give the file being uploaded	Yes

Upon successful upload, the results will provide the list of series paths and image layer paths for the uploaded file.

success response:

{
    "status":"success",
    "count":1,
    "results":[
        {
            "file name":'example.dcm',
            "series path":['NFCTDicomImagePath',
                {
                    'organization': $ORGANIZATION_ID,
                    'series uid': '1.3.46.670589.11.0.0.11.4.2.0.8743.5.5396',
                    'study uid': '2.16.840.1.113669.632.20.1211'
                }
            ],
            "layer paths":[
                       ['NFCTDicomImagePath',
                          {
                             'instance number': 91,
                             'layer index': 91,
                             'layer uid': '1.3.46.670589.11.0.0.11.4.2.0.8743.5.5396',
                             'organization': $ORGANIZATION_ID,
                             'series uid': '1.3.46.670589.11.0.0.11.4.2.0.8743.5.5396',
                             'study uid': '2.16.840.1.113669.632.20.1211'
                          }
                       ],
                       ['NFCTDicomImagePath',
                          {
                             'instance number': 92,
                             'layer index': 92,
                             'layer uid': '1.3.46.670589.11.0.0.11.4.2.0.8743.5.5396',
                             'organization': $ORGANIZATION_ID,
                             'series uid': '1.3.46.670589.11.0.0.11.4.2.0.8743.5.5396',
                             'study uid': '2.16.840.1.113669.632.20.1211'
                          }
                       ],
                       [ 
                          (... next image layer path info ...)
                       ]
            ],
            "upload":"completed",
            "processing":"in progress"
        }
    ]
}

Note that the actual file data is not specified through the query string; it is supplied in the request body. Here is an example using the python requests module:

data = {
    'action':'upload',
    'step':'upload_file',
    'file_name':'dicom.dcm',
    'upload_id':assignedId,
    'access_token':token
}
filesInfo = {
    'file':open(file_name, 'rb')
}

response = requests.post(endpoint, data=data, files=filesInfo, verify=False)

Indicate all file uploads for this upload ID are done

After all files have finished uploading, issue an upload completion request:

endpoint	/api/dicom
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	upload	Yes
step	upload_id_complete	Yes
upload_id	the upload id	Yes
file_count	the number of files for this upload. This is a check to ensure that the correct number of files were uploaded.	Yes

This notifies Jack Imaging that the client has finished issuing upload requests and that the uploads have all finished. Jack Imaging will then begin processing the uploaded files. The user for whom the access token is valid will be notified via email when processing is completed.

success response:

{
    "status":"success",
    "count":1,
    "results":[{
        "status":"success"
    }]
}

Patient cases

A Jack Imaging case consists of notes, conversations, DICOM images, and uploaded files such as pdfs or jpgs. Multiple users can participate in a case. Each user is assigned a role and permissions. Only a user who has accepted an invite to a case can view any part of the case.

List cases

List all the cases for which the user is a participant. A user is a participant of a case if she has accepted an invite to a case or she is participating in a consultation which contains the case.

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	list	Yes

success response:

{
    "status": "success",
    "count": 2,
    "results": [
        {
            "creation timestamp": 422314926,
            "container": "974658b1-e067-11e3-a528-7536a04e70f1",
            "name": "Consultation case \"consult\"",
            "patient name": "Patient Name",
            "creator name": "Doctor Feelgood",
            "patient email": "patient@patient.com",
            "user status": "active",
            "creator email": "doctorfeelgood@health.org",
            "identifier": "96851042-e067-11e3-9ef3-001c42b4b074",
            "permissions": ["owner"]
        },
        {
            "creation timestamp": 425507346,
            "container": null,
            "name": "Test for API",
            "patient name": "Patient Name",
            "creator name": "Doctor Jazz",
            "patient email": "patient@patient.com",
            "user status": "active",
            "creator email": "doctorjazz@health.org",
            "identifier": "85fb99f1-fd70-11e3-b284-159dd2d14723",
            "permissions": ["manager"]
        }
    ]
}

The identifier for items in the results array represents the case's id and is used for almost every other case-related API action.

A container is something of which a case is a part. For example, a consultation might contain a case. If the case has a container defined, then the users of the container represent the users of the case. In such a situation, editing the case users with the Jack Imaging API will have no effect.

The user status indicates the status of the requesting user relative to the case. A case may have multiple users, each with their own statuses.

The permissions indicates the list of permissions the requester has for this case. Note that having the owner permission does not necessarily mean the user has the role of creator.

Also note that the creation timestamp is likely to change into something human readable eventually. Currently it references an arbitrary epoch time.

Create a case

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	create	Yes
name	a name for the case	Yes
patient	email address for the patient	Yes

success response:

{
    'status':'success',
    'count':1,
    'results': [
        {
            'creator email': 'doctor@doctor.com',
            'creator name': 'Doctor Doctor Give Me The News',
            'entry': {
                'container': None,
                'creation timestamp': 432236386,
                'creator': 'doctor@doctor.com',
                'patient': 'nephosity/patient@patient.com'
            },
            'identifier': 'c98bae60-3aa3-11e4-9dcd-001c42fe7c38',
            'name': 'Patient's case',
            'patient email': 'patient@patient.com',
            'patient name': 'Patient',
            'permissions': ['manager'],
            'user status': 'active'
        }
    ],
}

The container, if not None, displays the consultation identifier which contains this case.

Remove a case

Note that removing a case simply means the user no longer has access to the case. He is removing himself from the case's list of users. Users still participating in the case can access the case normally.

Owners cannot remove cases, since that would leave the case without an owner. Reassign ownership first. See the permissions and roles case API documentation.

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	remove	Yes
case_identifier	a case identifier, obtainable with the list action	Yes

success response:

{
    'status': 'success',
    'count': 1,
    'results': [
        {
            'name': 'the deleted case',
            'case_identifier': '654e5c18-3aa8-11e4-97a1-001c42fe7c38',
            'cases': {
                '055486fc-2bb2-11e4-962c-001c42fe7c38': {
                    'entry': {
                        'container': 'f5b09591-2f05-11e4-aa05-d16582cb9e9b',
                         'creation timestamp': 430593232,
                         'creator': 'nephosity/doctor@doctor.com',
                         'identifier': '055486fc-2bb2-11e4-962c-001c42fe7c38',
                         'name': 'Consultation case "A consultation"',
                         'patient': 'nephosity/patient@patient.com'
                    },
                    'permissions': ['owner'],
                    'user status': 'active'
                }
            },
        }
    ],
}

The results list the name and id of the deleted case. The cases data structure lists the remaining cases to which the user has access.

Case media

Case media consist of dicoms, pdfs, jpgs, etc.

List media associated with the case

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	list_media	Yes
case_identifier	a case identifier, obtainable with the list action	Yes

success response:

{
    'status':'success',
    'count':3,
    'results':[
        {
            'identifier':12345,
            'name':'A Study',
            'media format':'dicom'
        },
        {
            'identifier':12346,
            'name':'A jpeg',
            'media format':'jpeg',
            'linked media':{},
            'url':'URL_TO_DOWNLOAD'
        },
        {
            'identifier':12347,
            'name':'A note',
            'media format':'note',
            'linked media':{}
        },

    ]
}

Media format will be 'dicom' for a DICOM series, 'pdf' for an Adobe Acrobat file, and so on.

Upload media to case

Cases can contain media other than DICOM studies. This method is not for uploading DICOM images. For example the user might upload a PDF or jpg. Uploading such files to the case automatically associates them with the case, whereas DICOM studies must be explicitly attached to a case.

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	upload	Yes
case_identifier	a case identifier, obtainable with the list action	Yes
format	file format, such as pdf or jpg	Yes
content_type	a generic description of the file's contents such as "pathology slide" (defaults to blank)	No
name	a name for the uploaded file (defaults to blank)	No
description	a specific description of the file's contents (defaults to blank)	No

The file must be the body of the POST request. For example the python requests module would specify a request like this:

endpoint = 'https://jackimaging.com/api/case'
params = {
    'action':'upload',
    'case_identifier':'abcd1234',
    'name':'diagnosis.pdf',
    'format':'pdf',
    'access_token':'thisisavalidaccesstoken1234',
    'description':'Dr. Smith's diagnosis',
    'content_type':'diagnosis'
    }
file = {
    'file':open(the_file_name, 'rb')
    }
response = requests.post(endpoint, data=params, files=file)

Note that the client should only specify one file per upload request. Only the first file will be uploaded; others will be ignored.

success response:

{
    "status": "success",
    "count": 1,
    "results": [
        {
            "description": "Dr. Smith's diagnosis",
            "format": "pdf",
            "content type": "diagnosis",
            "case identifier": "abcd1234",
            "identifier": "5ee5d0ba-00b8-11e4-a9e8-001c42b4b074",
            "name": "diagnosis.pdf"
        }
    ]
}

Attach DICOM study to case

You can attach a DICOM study to a case. It must be uploaded before it can be attached.

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	attach_study	Yes
case_identifier	a case identifier, obtainable with the list action	Yes
studyuid	a studyuid, obtainable with the dicom list action	Yes
name	the name for the study, if different from the study's title	No

success response:

{
    'status': 'success',
    'count': 1,
    'results': [
        {
            'identifier': 'faa08358-3aa9-11e4-865b-001c42fe7c38',
            'case_identifier': '055486fc-2bb2-11e4-962c-001c42fe7c38',
            'entry': {
                'case': '055486fc-2bb2-11e4-962c-001c42fe7c38',
                'identifier': 'faa08358-3aa9-11e4-865b-001c42fe7c38',
                'is active': True,
                'media format': 'dicom',
                'media identifier': '2.16.840.1.113669.632.20.1211.10000357775',
                'name': 'BRAINIX/IRM c\xe9r\xe9brale, neuro-cr\xe2ne',
                'organization': 'nephosity'
            }
        }
    ]
}

The identifier in the results is a case media identifier. It is suitable for use with, for example, the remove case media action.

Remove media from case

You can detach media from a case. The list of documents for the case will no longer contain the indicated media.

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	remove_media	Yes
case_identifier	a case identifier, obtainable with the list action	Yes
identifier	a media identifier, obtainable with the list_media action	Yes

Note that if the media identifier is incorrect, the client may not receive a very informative error response.

success response:

{
    "status": "success",
    "count": 1,
    "results": [
        {
            "case_identifier": "08554c91-fe55-11e3-b9e9-b5ce3e1ec693",
            "identifier": "46ff37c2-00d4-11e4-af38-001c42b4b074"
        }
    ]
}

Download media from case

If a user is able to view a case, he is able to download media from that case.

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	download_media_url	Yes
case_identifier	a case identifier, obtainable with the list action< /td>	Yes
identifier	a media identifier, obtainable with the list_media action	Yes

The response is an array of download URLs which can be used to download the specified media.

success response:

{
    "status": "success",
    "count": 1,
    "results": [
        "https://jackimaging.com/api/download_media?type=case_associated_media&entry_identifier=57bc37ce-0154-11e4-b5e9-001c42b4b074"
    ]
}

The url provided by the results of the download_media_url action, if successful, will respond with an HTTP 200 code, along with the contents of the file in the response body. If something goes wrong, then another HTTP error code will be issued, and the response body will be an explanation of the error

If you attempt to download a study or series attached to a case with this method, you will see an error like this:

{
    'status': 'error',
    'explanation': 'The media is a DICOM file(s) which should be downloaded with the /api/dicom API path'
}

Case users

Every case has at least one user to start with: the creator. The creator can also specify a patient, which may be himself. Any user of the case with management permissions can invite other users.

Note that cases might have a container attribute with a non-null value, obtainable with the list action. In such a situation, the container's users represent the case's users and cannot be manipulated through the case user API.

List case users

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	list_users	Yes
case_identifier	a case identifier, obtainable with the list action	Yes

success response:

{
    "status": "success",
    "count": 1,
    "results": [
        {
            "status": "active",
            "identifier": "nephosity/foo@bar.com",
            "name": "Foo Bar",
            "roles": ["patient"],
            "permissions": ["owner"]
        }
    ]
}

This example response indicates there is one user of the case that is simultaneously the patient and the owner of the case.

Invite user to case

To invite another user to a case a user must have manager or owner permissions.

You may not invite a user to a case while simultaneously granting them owner permissions.

See the edit case user documentation for more information on permissions and roles.

A user who has accepted an invite to a case cannot be invited again.

Note that inviting a user to a case is not the same as inviting a user to become a contact.

Yes

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	invite	Yes
case_identifier	a case identifier, obtainable with the list action
user_identifier	a user's email address or literal user identifier. See the is_email parameter.	Yes
is_email	0 (false) or 1 (true, default)	No
role	an arbitrary string describing the invited user's relation to the case. Defaults to 'other'	No
permission	one of four possible strings: owner, manager, contributor, viewer. Defaults to viewer, the lowest possible permission level	No

The is_email parameter specifies whether the user identifier is an email address or a literal Jack Imaging user id, obtainable with the list_user action.

success response:


{
    'status': 'success',
    'count': 1,
    'results': [
        {
            'case users info': {
                'nephosity/user1@gmail.com': {
                    'consultation': 'f5b09591-2f05-11e4-aa05-d16582cb9e9b',
                    'display name': ' ',
                    'group': 'user_nephosity/user1@gmail.com',
                    'is active': True,
                    'permissions': ['manager'],
                    'role': 'patient',
                    'roles': ['patient'],
                    'status': 'active'
                },
                'nephosity/user2@gmail.com': {
                    'consultation': 'f5b09591-2f05-11e4-aa05-d16582cb9e9b',
                    'display name': ' ',
                    'group': 'user_nephosity/user2@gmail.com',
                    'is active': True,
                    'permissions': ['owner'],
                    'role': 'other',
                    'roles': ['other'],
                    'status': 'active'
                }
            },
            'case_identifier': '055486fc-2bb2-11e4-962c-001c42fe7c38',
            'permission': 'contributor',
            'role': 'family member',
            'user_email': 'invitedUser@gmail.com',
            'user_identifier': 'nephosity/invitedUser@gmail.com'
        }
    ],
}

The case users info lists active members of the case; the invited user is listed outside of that info.

Remove user from case

To remove another user from a case, the requesting user must have manager or owner permissions.

A user may not remove the owner from a case. Reassign ownership first.

A user may always remove herself if she is not the owner, regardless of her permission level.

The user must have accepted the invite to the case before they can be removed.

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	remove_user	Yes
case_identifier	a case identifier, obtainable with the list action	Yes
user_identifier	a user identifier, obtainable with the list_users action	Yes

success response:

{
    "status": "success",
    "count": 1,
    "results": [
        {
            "case_identifier": "1a397331-021c-11e4-a83a-7b45cb8d8d8f",
            "user_identifier": "nephosity/foo@bar.com",
            "case users info": {
                "a_user_identifier" : {
                    "case": "a_case_identifier",
                    "code": "XXX",
                    "display name": "User Name",
                    "identifier": "an_identifier",
                    "is referral": false,
                    "permissions": [ "owner" ],
                    "recipient": "a_user_identifier",
                    "recipient email": "a_user_email",
                    "role": "patient",
                    "roles": [ "patient" ],
                    "sender": "another_user_identifier",
                    "share timestamp":428972668,
                    "status": "invited"
                }
            }
        }
    ]
}

Edit case user permissions and roles

A case user has a role assigned to him. For example a role might be 'patient' or 'primary care physician'. It is an arbitrary string specified at invite time.

A user also has a permission for a case. There are only four permissions possible.

viewer: can only view and download documents
contributor: viewer, plus can add images, media, and notes
manager: contributor, plus can add and remove users and their permissions (cannot remove owner)
owner: manager, plus can set owner

Only owners can grant ownership to someone else, at which point the original owner becomes a manager. Only one owner is allowed at a time.

Owners cannot demote themselves to manager; they must set someone else as owner first. This ensures there is always an owner.

Managers cannot demote themselves to contributor/viewer, but can be demoted by other managers or the owner.

Only one user at a time may have the role 'patient'. If another user is set to the patient, the former patient receives the role 'other'.

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	edit_user	Yes
case_identifier	a case identifier, obtainable with the list action	Yes
user_identifier	a user identifier, obtainable with the list_users action	Yes
role	a role (any string)	No
permission	one of the four valid permissions	No

If role or permission is not specified, it is left unchanged.

success response:

{
    'status': 'success',
    'count': 1,
    'results': [
        {
            'case users info': {
                'nephosity/userB@gmail.com': {
                    'case': 'a7cc608e-3ae0-11e4-b849-001c42fe7c38',
                    'display name': ' ',
                    'group': 'user_nephosity/userB@gmail.com',
                    'is active': True,
                    'permissions': ['owner'],
                    'role': 'new role',
                    'roles': ['new role'],
                    'status': 'active',
                    'timestamp': 432262529
                },
                'nephosity/userA@gmail.com': {
                    'case': 'a7cc608e-3ae0-11e4-b849-001c42fe7c38',
                    'display name': ' ',
                    'group': 'user_nephosity/userA@gmail.com',
                    'is active': True,
                    'permissions': ['manager'],
                    'role': 'other',
                    'roles': ['other'],
                    'status': 'active',
                    'timestamp': 432262529
                }
            },
            'case_identifier': 'a7cc608e-3ae0-11e4-b849-001c42fe7c38',
            'role': 'new role',
            'permission': 'owner',
            'user_identifier': 'nephosity/userB@gmail.com'
        }
    ],
}

In this example response userB has been given a new role and permission.

Note: the success response only contains the new role or permission if it was specified in the initial request.

Case notes

Case participants with contributor or greater permissions can add notes to the case. Notes have a title and text.

List case notes

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	list_notes	Yes
case_identifier	a case identifier, obtainable with the list action	Yes

success response:

{
    "status": "success",
    "count": 2,
    "results": [
        {
            "identifier": "636d9c94-045f-11e4-a230-001c42b4b074",
            "creator": "nephosity/doctor@health.org",
            "text": "Case needs referral to a specialist",
            "title": "Needs specialist",
            "template": "unstructured",
            "timestamp": 426269646
        },
        {
            "identifier": "748fe1be-0471-11e4-b879-001c42b4b074",
            "creator": "nephosity/specialist@health.org",
            "text": "We should do a biopsy",
            "title": "Re: Case needs referral to a specialist",
            "template": "unstructured",
            "timestamp": 426277406
        }
    ]
}

Add case note

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	add_note	Yes
case_identifier	a case identifier, obtainable with the list action	Yes
title	a title for the note	No
text	the text of the note	No

success response:

{
    "status": "success",
    "count": 1,
    "results": [
        {
            "title": "Hello",
            "text": "I am requesting a second opinion",
            "creator": "nephosity/foo@bar.com",
            "template": "unstructured",
            "timestamp": 426277406,
            "identifier": "748fe1be-0471-11e4-b879-001c42b4b074"
        }
    ]
}

Remove case note

endpoint	/api/case
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	remove_note	Yes
case_identifier	a case identifier, obtainable with the list action	Yes
note_identifier	note identifier, obtainable with the list_notes action	Yes

success response:

{
    "status": "success",
    "count": 1,
    "results": [
        {
            "association_identifier": "a9ad982e-3ae4-11e4-865b-001c42fe7c38",
            "note_identifier": "748fe1be-0471-11e4-b879-001c42b4b074",
            "case_identifier": "8797df71-023f-11e4-80dd-6fac609e2837"
        }
    ]
}

Contacts

A contact is another Jack Imaging user to whom you are connected.

List contacts

List users to whom you are connected.

endpoint	/api/connection
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	list	Yes
invites	0 or 1 (defaults to 0, false) -- show only contacts who've invited you	No

success response:

{
    'status': 'success',
    'count': 3,
    'results': [
        {   'email': 'user+b@gmail.com',
            'identifier': 'nephosity/user+b@gmail.com',
            'online status': 'Offline',
            'relation': 'family',
            'status': 'sent request'
        },
        {
            'display name': ' ',
            'email': 'user+a@gmail.com',
            'identifier': 'nephosity/user+a@gmail.com',
            'online status': 'Offline',
            'status': 'accepted'
        },
        {
            'display name': ' ',
            'email': 'user@doximity.com',
            'identifier': 'doximity/367236',
            'online status': 'Offline',
            'status': 'received request'
        }
    ]
}

Invite contacts

To make a contact, you must invite them to connect.

Note that if you have previously declined an invitation to connect from a user, but subsequently invite that user, you will immediately become connected.

endpoint	/api/connection
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	invite_send	Yes
identifier	an email address or user identifier	Yes
identifier_is_email	0 or 1 (defaults to 1, true)	No
relation	your relation to this contact, e.g. 'Caregiver'	No

success response:

{
    'status': 'success',
    'count': 3,
    'results': [
        {
            'email': 'user+b@gmail.com',
            'identifier': 'nephosity/user+b@gmail.com',
            'online status': 'Offline',
            'relation': 'family',
            'status': 'sent request'
        },
        {
            'display name': 'John Doe',
            'email': 'user+a@gmail.com',
            'identifier': 'nephosity/user+a@gmail.com',
            'online status': 'Offline',
            'status': 'accepted'
        },
        {
            'email': 'user@doximity.com',
            'identifier': 'doximity/2356',
            'online status': 'Offline',
            'relation': 'primary care physician',
            'status': 'sent request'
        }
    ],
}

The response is simply an updated list of your connections.

Accept or decline a contact invite

With this API action, you may accept or decline an invite to become a contact. You may also ignore the invitation entirely, which of course requires no action at all.

Note that you may also accept an invite to connect by inviting the inviter. Thus if you have previously declined an invitation but then invite the inviter, you will immediately become connected.

If neither user has previously invited each other, use the invite_send action instead. You can determine whether two users have an extant invitation by looking at either user's list of contacts.

endpoint	/api/connection
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	invite_respond	Yes
identifier	an email address or user identifier	Yes
accept	0 or 1	Yes
identifier_is_email	0 or 1 (defaults to 1, true)	No

success response:

{
    'status': 'success',
    'count': 3,
    'results': [
        {
            'email': 'user+b@gmail.com',
            'identifier': 'nephosity/user+b@gmail.com',
            'online status': 'Offline',
            'relation': 'family',
            'status': 'sent request'
        },
        {
            'display name': 'John Doe',
            'email': 'user+a@gmail.com',
            'identifier': 'nephosity/user+a@gmail.com',
            'online status': 'Offline',
            'status': 'accepted'
        },
        {
            'email': 'user@doximity.com',
            'identifier': 'doximity/2356',
            'online status': 'Offline',
            'relation': 'primary care physician',
            'status': 'sent request'
        }
    ],
}

The response is simply an updated list of your connections.

Conversations

A conversation lets you exchange messages with other users.

List conversations

See all the conversations for which you are a participant or owner.

endpoint	/api/connection
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	list	Yes

success response:


{
    'status': 'success',
    'count': 1,
    'results': [
        {
            'create timestamp': 432313831,
            'identifier': '32e6c363-2ea6-49d5-9cb2-d2c6ca7bdcfd',
            'latest post create timestamp': 0,
            'owner': 'nephosity/patient@patient.com',
            'status': 'normal',
            'title': 'My pathology slides',
            'unread post count': 2,
            'visible post count': 6
        }
    ]
}

Create a conversation

endpoint	/api/connection
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	create	Yes
title	a title	No

success response:

{
    'status': 'success',
    'count': 1,
    'results': [
        {
            'create timestamp': 432315193,
            'identifier': '5b8a019c-c933-4912-bd10-0f3670398517',
            'owner': 'nephosity/patient@patient.com',
            'title': 'My X-ray'
        }
    ],
}

Archive or unarchive a conversation

A conversation's status indicates what that conversation is to a given participant. For example a participant may have archived the conversation; for them it is 'archived'. For others the status is 'normal'.

The required parameter 'action' must have an argument of either archive or unarchive.

Note that if you are not a participant of a thread (that is, you have not created any posts for it) archiving or unarchiving has no effect as you have no relationship to the thread other than, possibly, being the owner.

The conversation status is used to control whether a conversation is visible in the Jack Imaging user interface.

endpoint	/api/connection
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	archive \| unarchive	Yes
conversation_id	a conversation id	Yes

success response:

{
    'status':'success',
    'count':1,
    'results': [
        {
            "visible post count": 0,
             "status": "archived",
             "create timestamp": 424308398,
             "title": "My pathology slides",
             "owner": "nephosity/john.doe@gmail.com",
             "identifier": "cace77f4-902b-4ae2-b614-bcb5cbfcd514",
             "unread post count": 0,
             "latest post create timestamp": 0
        }
    ]
}

Note: The status will be the empty string '' if the conversation does not contain any posts by the user making the request. See above for more information.

Add a post to a conversation

endpoint	/api/connection
Parameter	Value	Required?
access_token	A valid access token, obtainable through the Authorization API	Yes
action	addpost	Yes
text	the post body	Yes
conversation_id	a conversation id, obtainable with the list action	Yes

success response:

{
    'status': 'success',
    'count': 1,
    'results': [
        {
            'conversation_id': '84896fd0-3dfc-11e4-bcb9-d95fc9fe7b28',
            'post_id': 'ab43e993-c90d-4b7b-b656-a15a0a8c1ed7',
            'text': 'I need someone to diagnose my MRI.  Can you help me?'
        }
    ],
}

Developer API Documentation

Usage notes

The Jack Imaging Authorization API

The Jack Imaging Content API

Jack Imaging Authorization API

Step 1. Present the Jack Imaging OAuth Dialog

Step 2. The user is prompted to authorize your application

Step 3. The client's redirect_uri receives an authorization code

Step 4. Exchange the authorization code for an access token

Step 5. Make requests to the Jack Imaging Content API

Jack Imaging Content API

User profile

List profile information

DICOM images

List DICOM series

List and download individual DICOM series files

Bundle all files in a series

Downloading the bundle

Upload DICOM images

Request an upload ID

Upload each file

Indicate all file uploads for this upload ID are done

Patient cases

List cases

Create a case

Remove a case

Case media

List media associated with the case

Upload media to case

Attach DICOM study to case

Remove media from case

Download media from case

Case users

List case users

Invite user to case

Remove user from case

Edit case user permissions and roles

Case notes

List case notes

Add case note

Remove case note

Contacts

List contacts

Invite contacts

Accept or decline a contact invite

Conversations

List conversations

Create a conversation

Archive or unarchive a conversation

Add a post to a conversation