Page History
Anchor | ||||
---|---|---|---|---|
|
Section | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Service Endpoints
Multiexcerpt |
---|
Inside the NIH Firewall (VPN required)
Outside of the NIH Firewall
|
Access Requirements
Multiexcerpt |
---|
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
Multiexcerpt |
---|
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: 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 reports Subject & Partial Subject accrual information for a specific participating site on a trialstudy. 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 report 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}
- {id}. CTRP numeric identifier of a participating site
- Example: https://trials-stage.nci.nih.gov/accrual-services/sites/121787425
- /trials/{idType}/{trialID}/sites/po/{id}
- {idType}. Type of identifier you want to use to identify a trial in study in CTRP. Possible values: pa, nci, ctep, dcp.
- {trialID}. Trial identifier value itself
{id}. PO identifier of the organization that is the site on the trialstudy
- Example: https://trials-int.nci.nih.gov/accrual-services/trials/nci/NCI-2019-00038/sites/po/7434
- {idType}. Type of identifier you want to use to identify a trial in study in CTRP. Possible values: pa, nci, ctep, dcp.
- /trials/{idType}/{trialID}/sites/ctep/{id}
- {idType}. Type of identifier you want to use to identify a trial in study in CTRP. Possible values: pa, nci, ctep, dcp.
- {trialID}. Trial identifier value itself
{id}. CTEP identifier of the organization that is the site on the trialstudy
- 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 reporting 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.
...
The following XML request shows an example for submitting one reporting 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.
...
The following XML request shows an example for submitting one reporting one study subject to site 121787425 using Legacy Codes - CTEP for the disease code.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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 reporting 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.
...
The following XML request shows an example for submitting reporting one study subject to site 7434 using ICD-O-3 for the disease code with <disease> and <siteDisease> included.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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) trialstudy.
HTTP Method
PUT
URL
Three options are available:
- /sites/{siteID}/count?count={count}&cutOffDt={cutOffDate}
- {siteID}. CTRP numeric identifier of a participating site.
- {count}. Mandatory parameter. The accrual count for the site.
- {cutOffDate} . The cut-off date for the accrual count, in the format MM-DD-YYYY.
- Example: https://trials-stage.nci.nih.gov/accrual-services/sites/28577/count?count=10&cutOffDt=03-10-2015
- /trials/{idType}/{/trials/{idType}/{trialID}/sites/po/{poid}/ count?count={count}&cutOffDt={cutOffDate}
- {idType}. Type of identifier you want to use to identify a trial in study in CTRP. Possible values: pa, nci, ctep, dcp.
- {trialID}. Trial identifier value itself.
{poid}. PO identifier of the organization that is the site on the trialstudy.
- {count}. Mandatory parameter. The accrual count for the site.
- {cutOffDate} . The cut-off date for the accrual count, in the format MM-DD-YYYY.
- Example: https://trials
- /trials/{idType}/{trialID}/sites/ctep/{id}/ count?count={count}&cutOffDt={cutOffDate}
- {idType}. Type of identifier you want to use to identify a trial in study in CTRP. Possible values: pa, nci, ctep, dcp.
- {trialID}. Trial identifier value itself.
{id}. CTEP identifier of the organization that is the site on the trialstudy.
- {count}. Mandatory parameter. The accrual count for the site.
- {cutOffDate} . The cut-off date for the accrual count, in the format MM-DD-YYYY.
Request Body
None.
Response Body
Request Body
None.
Response Body
None (if successful) or an error message. MIME Type: text/plain
.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) |
URL Examples
https://trials-stage.nci.nih.gov/accrual-services/accrual-services/sites/28577/count?count=10&cutOffDt=03-10-2015
https://trials-stage.nci.nih.gov/accrual-services/trials/nci/NCI-2009-00939/sites/po/24567/count?count=10&cutOffDt=03-10-2015
https://trials-stage.nci.nih.gov/accrual-services/trials/nci/NCI-2009-00939/sites/ctep/CA067/count?count=135&cutOffDt=03-10-2015
...
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}
- {siteID}. CTRP numeric identifier of a participating site
- {subjectID}. Study subject identifier
- {siteID}. CTRP numeric identifier of a participating site
- {subjectID}. Study subject identifier
- Example: https://trials-stage.nci.nih.gov/accrual-services/sites/28577/subjects/SU001
- /trials/{idType}/{trialID}/sites/po/{poid}/subjects/{subjectID}
- {idType}. Type of identifier you want to use to identify a trial in study in CTRP. Possible values: pa, nci, ctep, dcp.
- {trialID}. Trial identifier value itself
{poid}. PO identifier of the organization that is the site on the trial
- {subjectID}. Study subject identifier
on the study
- {subjectID}. Study subject identifier
- 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}
- {idType}. Type of identifier you want to use to identify a trial in study in CTRP. Possible values: pa, nci, ctep, dcp .
- {trialID}. Trial identifier value itself
{ctepID}. CTEP identifier of the organization that is the site on the trialstudy
- {subjectID}. Study subject identifieridentifier
- 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 |
Examples
URL: https://trials-stage.nci.nih.gov/accrual-services/trials/nci/NCI-2014-00233/sites/po/12733422/subjects/SU001
...
Report 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 userreporting user.
HTTP Method
Post
URL
/batch
Request Body
XML document with batchFile root element.
...
None (if successful) or an error message. MIME Type: text/plain
.
Example
...
URL: https://trials-stage.nci.nih.gov/accrual-services/batch
Content-Type: application/xml
Accept: application/xmlBody:
Request Body
XML document with batchFile root element.
In this example, consider the following CDUS Accrual information for a typical CDUS Accrual file:
...
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:Multiexcerpt include MultiExcerptName ExitDisclaimer nopanel true PageWithExcerpt wikicontent:Exit Disclaimer to Include Code Block IkNPTExFQ1RJT05TIiwiTkNJLTIwMTQtMDI1OTMiLCwsLCwsLCwsDQoiUEFUSUVOVFMiLCJOQ0ktMjAxNC0wMjU5MyIsImcyIiwiMjA4NTAiLCJVUyIsIjE5ODAwMyIsIk1hbGUiLCJOb3QgUmVwb3J0ZWQiLCJNZWRpY2FpZCBhbmQgTWVkaWNhcmUiLCIyMDE0MDkzMCIsLCIxMjA4OTQiLCwsLCwsLCwsLCIyNTAuMDIiLCwNCiJQQVRJRU5UX1JBQ0VTIiwiTkNJLTIwMTQtMDI1OTMiLCJnMiIsIldoaXRlIg==
Insert the Base64 encoded text between <batchFile xmlns="gov.nih.nci.accrual.webservices.types"> and </batchFile> tags, as follows:
Code Block <batchFile xmlns="gov.nih.nci.accrual.webservices.types">IkNPTExFQ1RJT05TIiwiTkNJLTIwMTQtMDI1OTMiLCwsLCwsLCwsDQoiUEFUSUVOVFMiLCJOQ0ktMjAxNC0wMjU5MyIsImcyIiwiMjA4NTAiLCJVUyIsIjE5ODAwMyIsIk1hbGUiLCJOb3QgUmVwb3J0ZWQiLCJNZWRpY2FpZCBhbmQgTWVkaWNhcmUiLCIyMDE0MDkzMCIsLCIxMjA4OTQiLCwsLCwsLCwsLCIyNTAuMDIiLCwNCiJQQVRJRU5UX1JBQ0VTIiwiTkNJLTIwMTQtMDI1OTMiLCJnMiIsIldoaXRlIg==</batchFile>
Response Body
None (if successful) or an error message. MIME Type: text/plain
.