NCI CTRP Accrual REST Service Guide - Include v4.5a

Topic Links

This section provides instructions for managing subject accruals via the NCI CTRP Accrual REST Service.

Introduction

The Accrual REST Service is a CTRP Web Service that provides the following operations in a REST-like fashion:

Add or update trial subject accrual information on a given participating site
Delete specific trial subject accrual information from a given participating site
Submit accrual count for a participating site in an Abbreviated trial

The service uses XML for data exchange.

Service Endpoints

Inside the NIH Firewall (VPN required)

DEVINT: https://trials-int.nci.nih.gov/accrual-services

Outside of the NIH Firewall

STAGE: https://trials-stage.nci.nih.gov/accrual-services
PROD: https://trials.nci.nih.gov/accrual-services

Access Requirements

To use the service, you must have a valid NCI LDAP account and a CTRP account. For instructions, refer to Creating New NCI CTRP User Accounts. All service endpoints require HTTP Basic authentication with your NCI LDAP username and password.

API Specification

XML Schema

The service uses XML for data exchange. All XML elements going in or out of the service are defined and validated against the following XML schema:

accrual_ws.xsd

The XML schema is well-annotated with inline documentation that explains the purpose and meaning of various elements, types, and attributes. Specific elements required for service operations are explained in the sections below.

Add/Update Accruals - Subject & Partial Subject

Description

This operation submits Subject & Partial Subject accrual information for a specific participating site on a trial. If the subject accrual record already exists for the specified study and participating site, this operation will update that record accordingly. If you submit multiple Subject accrual records all with the same subject ID within the same request, the last record in the list will supplant the others. The submitter must have accrual access to the site.

HTTP Method

PUT

URL

Three options are available:

/sites/{id}
1. {id}. CTRP numeric identifier of a participating site
2. Example: https://trials-stage.nci.nih.gov/accrual-services/sites/121787425
/trials/{idType}/{trialID}/sites/po/{id}
1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp.
2. {trialID}. Trial identifier value itself
3. {id}. PO identifier of the organization that is the site on the trial
4. Example: https://trials-int.nci.nih.gov/accrual-services/trials/nci/NCI-2019-00038/sites/po/7434
/trials/{idType}/{trialID}/sites/ctep/{id}
1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp.
2. {trialID}. Trial identifier value itself
3. {id}. CTEP identifier of the organization that is the site on the trial
4. Example: https://trials-int.nci.nih.gov/accrual-services/trials/nci/NCI-2019-00038/sites/ctep/WQ456

Request Body

XML document with studySubjects root element (see XML Schema). MIME Type: application/xml.

Examples - Subject Accrual

Request XML:

The following XML request shows an example for submitting five study subjects to site 121787425 using ICD9 for disease codes. Note that the <siteDisease> is not required since the disease code used is ICD9.

<tns:studySubjects xmlns:tns="gov.nih.nci.accrual.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="gov.nih.nci.accrual.webservices.types ../../src/resources/ws.xsd ">
    <tns:studySubject>
        <tns:identifier>SU001</tns:identifier>
        <tns:birthDate>2002-01-01</tns:birthDate>
        <tns:gender>Female</tns:gender>
        <tns:race>Black or African American</tns:race>
        <tns:ethnicity>Not Hispanic or Latino</tns:ethnicity>
        <tns:country>USA</tns:country>
        <tns:zipCode>22201</tns:zipCode>
        <tns:registrationDate>2014-01-01</tns:registrationDate>
        <tns:methodOfPayment>MEDICAID_AND_MEDICARE</tns:methodOfPayment>
        <tns:disease codeSystem="ICD9">861.20</tns:disease>        
    </tns:studySubject>
    <tns:studySubject>
        <tns:identifier>SU002</tns:identifier>
        <tns:birthDate>2002-01-01</tns:birthDate>
        <tns:gender>Male</tns:gender>
        <tns:race>Native Hawaiian or Other Pacific Islander</tns:race>
        <tns:ethnicity>Not Reported</tns:ethnicity>
        <tns:country>CAN</tns:country>
        <tns:registrationDate>2014-01-01</tns:registrationDate>
        <tns:methodOfPayment>MILITARY_OR_VETERANS</tns:methodOfPayment>
        <tns:disease codeSystem="ICD9">861.20</tns:disease>        
    </tns:studySubject>
    <tns:studySubject>
        <tns:identifier>SU003</tns:identifier>
        <tns:birthDate>2002-01-01</tns:birthDate>
        <tns:gender>Unknown</tns:gender>
        <tns:race>American Indian or Alaska Native</tns:race>
        <tns:race>Asian</tns:race>
        <tns:race>Black or African American</tns:race>
        <tns:race>Native Hawaiian or Other Pacific Islander</tns:race>
        <tns:race>Not Reported</tns:race>
        <tns:race>Unknown</tns:race>
        <tns:race>White</tns:race>        
        <tns:ethnicity>Unknown</tns:ethnicity>
        <tns:country>CAN</tns:country>
        <tns:registrationDate>2014-01-01</tns:registrationDate>
        <tns:methodOfPayment>NO_MEANS_OF_PAYMENT</tns:methodOfPayment>
        <tns:disease codeSystem="ICD9">861.20</tns:disease>     
    </tns:studySubject>
    <tns:studySubject>
        <tns:identifier>SU004</tns:identifier>
        <tns:birthDate>2002-01-01</tns:birthDate>
        <tns:gender>Unspecified</tns:gender>
        <tns:race>Native Hawaiian or Other Pacific Islander</tns:race>
        <tns:ethnicity>Not Reported</tns:ethnicity>
        <tns:country>AFG</tns:country>
        <tns:registrationDate>2011-01-01</tns:registrationDate>
        <tns:methodOfPayment>STATE_SUPPLEMENTAL</tns:methodOfPayment>
        <tns:disease codeSystem="ICD9">861.20</tns:disease>     
    </tns:studySubject>
     <tns:studySubject>
        <tns:identifier>SU005</tns:identifier>
        <tns:birthDate>1990-01-01</tns:birthDate>
        <tns:gender>Female</tns:gender>
        <tns:race>American Indian or Alaska Native</tns:race>
        <tns:race>Asian</tns:race>
        <tns:race>Black or African American</tns:race>
        <tns:race>Native Hawaiian or Other Pacific Islander</tns:race>
        <tns:race>Not Reported</tns:race>
        <tns:race>Unknown</tns:race>
        <tns:race>White</tns:race>      
        <tns:ethnicity>Hispanic or Latino</tns:ethnicity>
        <tns:country>USA</tns:country>
        <tns:zipCode>22222</tns:zipCode>
        <tns:registrationDate>2014-01-01</tns:registrationDate>
        <tns:methodOfPayment>MANAGED_CARE</tns:methodOfPayment>
        <tns:disease codeSystem="ICD9">011.41</tns:disease>     
    </tns:studySubject>
</tns:studySubjects>

Request XML (Specifying Topography and Morphology codes using ICD-O-3)

The following XML request shows an example for submitting one study subject to site 121787425 using ICD-O-3 for the Topography code. Note that when the Topography <codeSystem> = “ICD-O-3”, both the <disease> and the <siteDisease> are mandatory.

<tns:studySubjects xmlns:tns="gov.nih.nci.accrual.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="gov.nih.nci.accrual.webservices.types ../../src/resources/ws.xsd ">
    <tns:studySubject>
        <tns:identifier>SU006</tns:identifier>
        <tns:birthDate>2002-01-01</tns:birthDate>
        <tns:gender>Female</tns:gender>
        <tns:race>Black or African American</tns:race>
        <tns:ethnicity>Not Hispanic or Latino</tns:ethnicity>
        <tns:country>USA</tns:country>
        <tns:zipCode>22201</tns:zipCode>
        <tns:registrationDate>2014-01-01</tns:registrationDate>
        <tns:methodOfPayment>MEDICAID_AND_MEDICARE</tns:methodOfPayment>
        <tns:disease codeSystem="ICD-O-3">8012/3</tns:disease>
        <tns:siteDisease codeSystem="ICD-O-3">C34.1</tns:siteDisease>
    </tns:studySubject>
</tns:studySubjects>

Request XML (Specifying Disease and Site Disease codes using Legacy Codes - CTEP)

The following XML request shows an example for submitting one study subject to site 121787425 using Legacy Codes - CTEP for the disease code.

<tns:studySubjects xmlns:tns="gov.nih.nci.accrual.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="gov.nih.nci.accrual.webservices.types ../../src/resources/ws.xsd ">
    <tns:studySubject>
        <tns:identifier>SU007</tns:identifier>
        <tns:birthDate>2002-01-01</tns:birthDate>
        <tns:gender>Female</tns:gender>
        <tns:race>American Indian or Alaska Native</tns:race>
        <tns:ethnicity>Not Hispanic or Latino</tns:ethnicity>
        <tns:country>USA</tns:country>
        <tns:zipCode>22201</tns:zipCode>
        <tns:registrationDate>2014-01-01</tns:registrationDate>
        <tns:methodOfPayment>MANAGED_CARE</tns:methodOfPayment>
        <tns:disease codeSystem="Legacy Codes - CTEP">10001418</tns:disease>
    </tns:studySubject>
</tns:studySubjects>

Examples - Partial Accrual

Request XML:

The following XML request shows an example for submitting one study subject to site 7434 using ICD-0-3 for the disease code. Note: for ICD-0-3 studies neither <disease> and <siteDisease> are mandatory. However, if <disease> is included then <siteDisease> must be included.

<tns:studySubjects xmlns:tns="gov.nih.nci.accrual.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="gov.nih.nci.accrual.webservices.types ../../src/resources/ws.xsd ">
    <tns:studySubject>
        <tns:identifier>SU100</tns:identifier>
        <tns:registrationDate>2014-01-01</tns:registrationDate>
    </tns:studySubject>
</tns:studySubjects>

Request XML:

The following XML request shows an example for submitting one study subject to site 7434 using ICD-O-3 for the disease code with <disease> and <siteDisease> included.

<tns:studySubjects xmlns:tns="gov.nih.nci.accrual.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="gov.nih.nci.accrual.webservices.types ../../src/resources/ws.xsd ">
    <tns:studySubject>
        <tns:identifier>SU101</tns:identifier>
        <tns:registrationDate>2014-01-01</tns:registrationDate>
		<tns:disease codeSystem="ICD-O-3">8012/3</tns:disease>
        <tns:siteDisease codeSystem="ICD-O-3">C34.1</tns:siteDisease>
    </tns:studySubject>
</tns:studySubjects>

Response Body

None (if successful) or an error message. MIME Type: text/plain.

HTTP Response Codes

Code	Response
200	Success
400	Validation error
404	Participating site not found
500	Internal server error

Update Accruals - Summary

Description

This operation updates accrual counts for a participating site on an Abbreviated (Industrial) trial.

HTTP Method

PUT

URL

Three options are available:

/sites/{siteID}/count?count={count}&cutOffDt={cutOffDate}
1. {siteID}. CTRP numeric identifier of a participating site.
2. {count}. Mandatory parameter. The accrual count for the site.
3. {cutOffDate} . The cut-off date for the accrual count, in the format MM-DD-YYYY.
4. Example: https://trials-stage.nci.nih.gov/accrual-services/sites/28577/count?count=10&cutOffDt=03-10-2015
/trials/{idType}/{trialID}/sites/po/{poid}/ count?count={count}&cutOffDt={cutOffDate}
1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp.
2. {trialID}. Trial identifier value itself.
3. {poid}. PO identifier of the organization that is the site on the trial.
4. {count}. Mandatory parameter. The accrual count for the site.
5. {cutOffDate} . The cut-off date for the accrual count, in the format MM-DD-YYYY.
6. Example: https://trials-int.nci.nih.gov/accrual-services/trials/nci/NCI-2018-03045/sites/po/7434/count?count=10&cutOffDt=03-10-2015
/trials/{idType}/{trialID}/sites/ctep/{id}/ count?count={count}&cutOffDt={cutOffDate}
1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp.
2. {trialID}. Trial identifier value itself.
3. {id}. CTEP identifier of the organization that is the site on the trial.
4. {count}. Mandatory parameter. The accrual count for the site.
5. {cutOffDate} . The cut-off date for the accrual count, in the format MM-DD-YYYY.
6. Example: https://trials-int.nci.nih.gov/accrual-services/trials/nci/NCI-2018-03045/sites/ctep/WQ456/count?count=20&cutOffDt=03-10-2015

Request Body

None.

Response Body

None (if successful) or an error message. MIME Type: text/plain.

HTTP Response Codes

Code	Response
200	Success
400	Validation error
401	Authentication/Authorization Failure: invalid username/password or insufficient permissions to access the service
404	Participating site/study subject not found
500	Internal server error (includes the condition of updating/deleting a study subject that you don't have accrual access to)

Delete Study Subject

Description

Deletes specific study subject (patient) accrual information from a participating site.

HTTP Method

DELETE

URL

Three options are available:

/sites/{siteID}/subjects/{subjectID}
1. {siteID}. CTRP numeric identifier of a participating site
2. {subjectID}. Study subject identifier
3. Example: https://trials-stage.nci.nih.gov/accrual-services/sites/28577/subjects/SU001
/trials/{idType}/{trialID}/sites/po/{poid}/subjects/{subjectID}
1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp.
2. {trialID}. Trial identifier value itself
3. {poid}. PO identifier of the organization that is the site on the trial
4. {subjectID}. Study subject identifier
5. Example: https://trials-stage.nci.nih.gov/accrual-services/trials/nci/NCI-2014-00233/sites/po/7434/subjects/SU001
/trials/{idType}/{trialID}/sites/ctep/{ctepID}/subjects/{subjectID}
1. {idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep, dcp .
2. {trialID}. Trial identifier value itself
3. {ctepID}. CTEP identifier of the organization that is the site on the trial
4. {subjectID}. Study subject identifier
5. Example: https://trials-stage.nci.nih.gov/accrual-services/trials/nci/NCI-2014-00233/sites/ctep/WQ456/subjects/SU001

Request Body

NONE

Response Body

None (if successful) or an error message. MIME Type: text/plain.

HTTP Response Codes

Code	Response
200	Success
400	Validation error
404	Study subject not found
500	Internal server error

Submit CDUS Batch File for Asynchronous Processing

Refer to the following on batch file formats: Complete Trial Data Record Formats, Abbreviated Trial Data Record Formats

Description

With this operation, you can upload a CDUS batch file. The system processes this file asynchronously and sends the results of processing by email to the submitting user.

HTTP Method

Post

URL

/batch

Example: https://trials-stage.nci.nih.gov/accrual-services/batch

Content-Type: application/xml

Accept: application/xml

Request Body

XML document with batchFile root element.

In this example, consider the following CDUS Accrual information for a typical CDUS Accrual file:

"COLLECTIONS","NCI-2014-02593",,,,,,,,, 
"PATIENTS","NCI-2014-02593","g2","20850","US","198003","Male","Not Reported","Medicaid and Medicare","20140930",,"120894",,,,,,,,,,"250.02",,
"PATIENT_RACES","NCI-2014-02593","g2","White"

How to Construct the Body:

Convert the CDUS Accrual information to Base64 encoding. You can do so using Base64 Encoding feature in the Notepad++ application. (Other tools can be found here: https://www.google.com/#q=base64+encoding+tool .) If you convert the above example information, the result would be as follows:

IkNPTExFQ1RJT05TIiwiTkNJLTIwMTQtMDI1OTMiLCwsLCwsLCwsDQoiUEFUSUVOVFMiLCJOQ0ktMjAxNC0wMjU5MyIsImcyIiwiMjA4NTAiLCJVUyIsIjE5ODAwMyIsIk1hbGUiLCJOb3QgUmVwb3J0ZWQiLCJNZWRpY2FpZCBhbmQgTWVkaWNhcmUiLCIyMDE0MDkzMCIsLCIxMjA4OTQiLCwsLCwsLCwsLCIyNTAuMDIiLCwNCiJQQVRJRU5UX1JBQ0VTIiwiTkNJLTIwMTQtMDI1OTMiLCJnMiIsIldoaXRlIg==

Insert the Base64 encoded text between <batchFile xmlns="gov.nih.nci.accrual.webservices.types"> and </batchFile> tags, as follows:

<batchFile xmlns="gov.nih.nci.accrual.webservices.types">IkNPTExFQ1RJT05TIiwiTkNJLTIwMTQtMDI1OTMiLCwsLCwsLCwsDQoiUEFUSUVOVFMiLCJOQ0ktMjAxNC0wMjU5MyIsImcyIiwiMjA4NTAiLCJVUyIsIjE5ODAwMyIsIk1hbGUiLCJOb3QgUmVwb3J0ZWQiLCJNZWRpY2FpZCBhbmQgTWVkaWNhcmUiLCIyMDE0MDkzMCIsLCIxMjA4OTQiLCwsLCwsLCwsLCIyNTAuMDIiLCwNCiJQQVRJRU5UX1JBQ0VTIiwiTkNJLTIwMTQtMDI1OTMiLCJnMiIsIldoaXRlIg==</batchFile>

Response Body

None (if successful) or an error message. MIME Type: text/plain.

Content

Space Tools

NCI CTRP Accrual REST Service Guide - Include v4.5a

Introduction

Service Endpoints

Access Requirements

API Specification

XML Schema

Add/Update Accruals - Subject & Partial Subject

Description

HTTP Method

URL

Request Body

Examples - Subject Accrual

Examples - Partial Accrual

Response Body

HTTP Response Codes

Update Accruals - Summary

Description

HTTP Method

URL

Request Body

Response Body

HTTP Response Codes

Delete Study Subject

Description

HTTP Method

URL

Request Body

Response Body

HTTP Response Codes

Submit CDUS Batch File for Asynchronous Processing

Description

HTTP Method

URL

Request Body

Response Body