NIH | National Cancer Institute | NCI Wiki  

Topic Links

This section provides instructions for adding and updating participating sites via the NCI CTRP Participating Site REST Service.

Introduction

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

  • Add a participating site to a trial
  • Update an existing participating site on a trial
  • Obtain a list of participating sites on a trial

The service uses XML for data exchange.

Program Codes

The program codes feature (not to be confused with NCI Division and Program Values) has been enhanced for the 4.4 release. The system ignores program codes unless the trial is one of the following:

  • Complete trial with a lead organization as a member of your cancer center family of organizations.
  • Abbreviated trial where such a member is a participant.

The system validates program code values against those listed on the Manage Program Codes Master List page for your affiliated cancer center. For details, refer to Managing Program Codes.

Service Endpoints

Inside the NIH Firewall (VPN required)

Outside of the NIH Firewall

Access Requirements

To use the service, you must have a valid NCI CTRP account. For instructions, refer to Creating New NCI CTRP User Accounts. All service endpoints require Okta token authentication with your NCI CTRP Client ID and Client Secret. Contact CTRP_support@nih.gov to have a NCI CTRP Client ID and Client secret generated for your CTRP REST account. 

See the following document for generating an Okta access token using your CTRP Client ID and Client Secret: NCI CTRP API Authentication Guide

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 schemas:

XML schemas are 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.

Persons and Organizations - Requirements and Recommendations

Creating or updating sites in the CTRP often involves organizations and persons that act as Healthcare Facilities and Principal Investigators on a site. CTRP does not manage information about persons and organizations; instead, this is delegated to the Person and Organization Curation Portal, also known as PO. For more information, refer to the NCI CTRP Person and Organization Curation User Guide.

You must have a user account with appropriate LDAP membership to access the PO User's Guide.

Before creating or updating a site, ensure that organizations and persons acting on the site exist already in PO. Use person identifiers (PO IDs) and organization identifiers (CTEP IDs) when you register a trial whenever possible. If they do not already exist, request that they be created prior to managing a site, by submitting a request to the CTRO at ncictro@mail.nih.gov.

Use PO Web Services API

We strongly recommend that you exercise the   PO Web Services API separately in order to find persons and organizations of interest prior to creating a site. Once you find a person or organization, you can use their IDs within a site creation packet as shown in API examples below. This helps to minimize duplicates in the CTRP system.

API Specification

Add Site

Adds a participating site to a trial.

HTTP MethodPOST
URL

/trials/{idType}/{trialID}/sites

Parameters

{idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep.

{trialID}. Trial identifier value itself

Request BodyXML document with
ParticipatingSite


MIME Type: application/xml

Response Body

CTRP identifier of the site

MIME Type: text/plain

HTTP Response Code
  • 200. Success
  • 400. Validation error
  • 401. Invalid username/password or insufficient permissions to access the service.
  • 404. Trial not found
  • 500. Internal server error (includes the condition when the caller does not own the trial)
Examples

URL: https://trials-dev.nci.nih.gov/services/trials/nci/NCI-2014-00496/sites

Request (referring to existing Organizations and Persons by ID): 

<tns:ParticipatingSite xmlns:tns="gov.nih.nci.pa.webservices.types"
    xmlns:tns1="gov.nih.nci.po.webservices.types.trimmed" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="gov.nih.nci.pa.webservices.types ../../src/resources/ws.xsd ">
    <tns:recruitmentStatus>Administratively Complete</tns:recruitmentStatus>
    <tns:recruitmentStatusDate>2001-05-06</tns:recruitmentStatusDate>
    <tns:localTrialIdentifier>tns:localTrialIdentifier</tns:localTrialIdentifier>
    <tns:programCode>tns:programCode</tns:programCode>
    <tns:openedForAccrual>2001-02-02</tns:openedForAccrual>
    <tns:closedForAccrual>2010-03-04</tns:closedForAccrual>
    <tns:targetAccrualNumber>100000</tns:targetAccrualNumber>
    <tns:investigator>
        <tns:person>
            <tns:existingPerson>
                <tns:poID>1</tns:poID>
            </tns:existingPerson>
        </tns:person>
        <tns:role>Principal Investigator</tns:role>
        <tns:primaryContact>true</tns:primaryContact>
    </tns:investigator>
    <tns:investigator>
        <tns:person>
            <tns:existingPerson>
                <tns:poID>2</tns:poID>
            </tns:existingPerson>
        </tns:person>
        <tns:role>Sub Investigator</tns:role>
        <tns:primaryContact>false</tns:primaryContact>
    </tns:investigator>
    <tns:organization>
        <tns:existingOrganization>
            <tns:poID>1</tns:poID>
        </tns:existingOrganization>
    </tns:organization>
</tns:ParticipatingSite>

 
 
 
Request (Referring to Generic Contacts for RSS Sites):
<?xml version="1.0" encoding="UTF-8"?>
<tns:ParticipatingSite xmlns:tns="gov.nih.nci.pa.webservices.types"
	xmlns:tns1="gov.nih.nci.po.webservices.types.trimmed" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="gov.nih.nci.pa.webservices.types ../../src/resources/ws.xsd ">
	<tns:recruitmentStatus>Administratively Complete</tns:recruitmentStatus>
	<tns:recruitmentStatusDate>2001-05-06</tns:recruitmentStatusDate>
	<tns:localTrialIdentifier>tns:localTrialIdentifier</tns:localTrialIdentifier>
	<tns:programCode>tns:programCode</tns:programCode>
	<tns:openedForAccrual>2001-02-02</tns:openedForAccrual>
	<tns:closedForAccrual>2010-03-04</tns:closedForAccrual>
	<tns:targetAccrualNumber>100000</tns:targetAccrualNumber>
	<tns:investigator>
		<tns:person>
			<tns:existingPerson>
				<tns:poID>1</tns:poID>
			</tns:existingPerson>
		</tns:person>
		<tns:role>Principal Investigator</tns:role>
		<tns:primaryContact>true</tns:primaryContact>
	</tns:investigator>
	<tns:investigator>
		<tns:person>
			<tns:existingPerson>
				<tns:poID>1</tns:poID>
			</tns:existingPerson>
		</tns:person>
		<tns:role>Principal Investigator</tns:role>
		<tns:primaryContact>false</tns:primaryContact>
	</tns:investigator>
	<tns:primaryContact>
		<tns:person>
			<tns:existingPerson>
				<tns:poID>1</tns:poID>
			</tns:existingPerson>
		</tns:person>
		<tns:contactDetails>
			<tns:email>richardroe@example.com</tns:email>
			<tns:phone>555-555-5555</tns:phone>
		</tns:contactDetails>
	</tns:primaryContact>
	<tns:organization>
		<tns:existingOrganization>
			<tns:poID>2</tns:poID>
		</tns:existingOrganization>
	</tns:organization>
</tns:ParticipatingSite>
Request (Referring to Generic Contacts for RSS Sites):
<?xml version="1.0" encoding="UTF-8"?>
<tns:ParticipatingSite xmlns:tns="gov.nih.nci.pa.webservices.types"
                       xmlns:tns1="gov.nih.nci.po.webservices.types.trimmed" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       xsi:schemaLocation="gov.nih.nci.pa.webservices.types ../../src/resources/ws.xsd ">
    <tns:recruitmentStatus>Administratively Complete</tns:recruitmentStatus>
    <tns:recruitmentStatusDate>2001-05-06</tns:recruitmentStatusDate>
    <tns:localTrialIdentifier>tns:localTrialIdentifier</tns:localTrialIdentifier>
    <tns:programCode>tns:programCode</tns:programCode>
    <tns:openedForAccrual>2001-02-02</tns:openedForAccrual>
    <tns:closedForAccrual>2010-03-04</tns:closedForAccrual>
    <tns:targetAccrualNumber>100000</tns:targetAccrualNumber>
    <tns:investigator>
        <tns:person>
            <tns:existingPerson>
                <tns:poID>1</tns:poID>
            </tns:existingPerson>
        </tns:person>
        <tns:role>Principal Investigator</tns:role>
        <tns:primaryContact>false</tns:primaryContact>
    </tns:investigator>
   <tns:genericContact>
       <tns:title>GenericContactTitle</tns:title>
       <tns:contactDetails>
           <tns:email>gc@example.com</tns:email>
           <tns:phone>111-111-1111</tns:phone>
       </tns:contactDetails>
   </tns:genericContact>
    <tns:organization>
        <tns:existingOrganization>
            <tns:poID>2</tns:poID>
        </tns:existingOrganization>
    </tns:organization>
</tns:ParticipatingSite>

Update Site

Updates a participating site on a trial.

HTTP MethodPUT
URL

/sites/{id}

Parameters

{id}. CTRP identifier of the site

/trials/{idType}/{trialID}/sites/po/{id}

Parameters

{idType}. Type of identifier used to identify a trial in CTRP. Possible values: pa, nci, ctep.

{trialID}. Trial identifier value itself

{id}. PO identifier of the organization that is the site on the trial

/trials/{idType}/{trialID}/sites/ctep/{id}

Parameters

{idType}. Type of identifier used to identify a trial in CTRP. Possible values: pa, nci, ctep.

{trialID}. Trial identifier value itself

{id}. CTEP identifier of the organization that is the site on the trial

Request BodyXML document with
ParticipatingSiteUpdate


MIME Type: application/xml

Response Body

CTRP identifier of the site.

MIME Type: text/plain.

HTTP Response Code

200. Success

400. Validation error

401. Invalid username/password or insufficient permissions to access the service.

404. Site not found

500. Internal server error (includes the condition when the caller does not own the trial)

Examples

URL: https://trials-dev.nci.nih.gov/services/trials/nci/NCI-2014-00496/sites/po/34758686

Request (referring to existing Organizations and Persons by ID): 

<tns:ParticipatingSiteUpdate xmlns:tns="gov.nih.nci.pa.webservices.types"
    xmlns:tns1="gov.nih.nci.po.webservices.types.trimmed" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="gov.nih.nci.pa.webservices.types ../../src/resources/ws.xsd ">
    <tns:recruitmentStatus>Administratively Complete</tns:recruitmentStatus>
    <tns:recruitmentStatusDate>2001-05-06</tns:recruitmentStatusDate>
    <tns:localTrialIdentifier>tns:localTrialIdentifier</tns:localTrialIdentifier>
    <tns:programCode>tns:programCode</tns:programCode>
    <tns:openedForAccrual>2001-02-02</tns:openedForAccrual>
    <tns:closedForAccrual>2010-03-04</tns:closedForAccrual>
    <tns:targetAccrualNumber>100000</tns:targetAccrualNumber>
    <tns:investigator>
        <tns:person>
            <tns:existingPerson>
                <tns:poID>1</tns:poID>
            </tns:existingPerson>
        </tns:person>
        <tns:role>Principal Investigator</tns:role>
        <tns:primaryContact>true</tns:primaryContact>
    </tns:investigator>
    <tns:investigator>
        <tns:person>
            <tns:existingPerson>
                <tns:poID>2</tns:poID>
            </tns:existingPerson>
        </tns:person>
        <tns:role>Principal Investigator</tns:role>
        <tns:primaryContact>false</tns:primaryContact>
    </tns:investigator>
	<tns:primaryContact>
		<tns:person>
            <tns:existingPerson>
                <tns:poID>1</tns:poID>
            </tns:existingPerson>
		</tns:person>
		<tns:contactDetails>
			<tns:email>sample@sample.com</tns:email>
			<tns:phone>555-555-5555ext99</tns:phone>
		</tns:contactDetails>
	</tns:primaryContact>
</tns:ParticipatingSiteUpdate>
Request (Referring to Generic Contacts for RSS Sites):


<?xml version="1.0" encoding="UTF-8"?>
<tns:ParticipatingSiteUpdate xmlns:tns="gov.nih.nci.pa.webservices.types"
	xmlns:tns1="gov.nih.nci.po.webservices.types.trimmed" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="gov.nih.nci.pa.webservices.types ../../src/resources/ws.xsd ">
	<tns:recruitmentStatus>Administratively Complete</tns:recruitmentStatus>
	<tns:recruitmentStatusDate>2001-05-06</tns:recruitmentStatusDate>
	<tns:localTrialIdentifier>tns:localTrialIdentifier</tns:localTrialIdentifier>
	<tns:programCode>tns:programCode</tns:programCode>
	<tns:openedForAccrual>2001-02-02</tns:openedForAccrual>
	<tns:closedForAccrual>2010-03-04</tns:closedForAccrual>
	<tns:targetAccrualNumber>100000</tns:targetAccrualNumber>
	<tns:investigator>
		<tns:person>
			<tns:existingPerson>
				<tns:poID>1</tns:poID>
			</tns:existingPerson>
		</tns:person>
		<tns:role>Principal Investigator</tns:role>
		<tns:primaryContact>true</tns:primaryContact>
	</tns:investigator>
	<tns:investigator>
		<tns:person>
			<tns:existingPerson>
				<tns:poID>1</tns:poID>
			</tns:existingPerson>
		</tns:person>
		<tns:role>Principal Investigator</tns:role>
		<tns:primaryContact>false</tns:primaryContact>
	</tns:investigator>
	<tns:primaryContact>
		<tns:person>
			<tns:existingPerson>
				<tns:poID>1</tns:poID>
			</tns:existingPerson>
		</tns:person>
		<tns:contactDetails>
			<tns:email>richardroe@example.com</tns:email>
			<tns:phone>555-555-5555</tns:phone>
		</tns:contactDetails>
	</tns:primaryContact>
</tns:ParticipatingSiteUpdate>
Request (Referring to Generic Contacts for RSS Sites):
 
<?xml version="1.0" encoding="UTF-8"?>
<tns:ParticipatingSiteUpdate xmlns:tns="gov.nih.nci.pa.webservices.types"
     xmlns:tns1="gov.nih.nci.po.webservices.types.trimmed" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="gov.nih.nci.pa.webservices.types ../../src/resources/ws.xsd ">
    <tns:recruitmentStatus>Administratively Complete</tns:recruitmentStatus>
    <tns:recruitmentStatusDate>2001-05-06</tns:recruitmentStatusDate>
    <tns:localTrialIdentifier>tns:localTrialIdentifier</tns:localTrialIdentifier>
    <tns:programCode>tns:programCode</tns:programCode>
    <tns:openedForAccrual>2001-02-02</tns:openedForAccrual>
    <tns:closedForAccrual>2010-03-04</tns:closedForAccrual>
    <tns:targetAccrualNumber>100000</tns:targetAccrualNumber>
    <tns:investigator>
        <tns:person>
            <tns:existingPerson>
                <tns:poID>1</tns:poID>
            </tns:existingPerson>
        </tns:person>
        <tns:role>Principal Investigator</tns:role>
        <tns:primaryContact>false</tns:primaryContact>
    </tns:investigator>
    <tns:investigator>
        <tns:person>
            <tns:existingPerson>
                <tns:poID>1</tns:poID>
            </tns:existingPerson>
        </tns:person>
        <tns:role>Principal Investigator</tns:role>
        <tns:primaryContact>false</tns:primaryContact>
    </tns:investigator>
    <tns:genericContact>
        <tns:title>GenericContactTitle</tns:title>
        <tns:contactDetails>
            <tns:email>gc@example.com</tns:email>
            <tns:phone>111-111-1111</tns:phone>
        </tns:contactDetails>
    </tns:genericContact>
</tns:ParticipatingSiteUpdate>



Get Sites

Retrieves a list of participating sites on a trial

HTTP MethodGET
URL

/trials/{idType}/{trialID}/sites

Parameters

{idType}. Type of identifier you want to use to identify a trial in CTRP. Possible values: pa, nci, ctep.

{trialID}. Trial identifier value itself.

Request BodyNONE
Response BodyXML document with
sites

MIME Type: application/xml.

HTTP Response Code

200. Success

401. Invalid username/password or insufficient permissions to access the service.

404. Trial not found

500. Internal server error

Examples

URL: https://trials-dev.nci.nih.gov/services/trials/nci/NCI-2014-00496/sites

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<sites xmlns="gov.nih.nci.pa.webservices.types" xmlns:ns2="gov.nih.nci.po.webservices.types.trimmed">
    <site>
        <recruitmentStatus>Active</recruitmentStatus>
        <recruitmentStatusDate>2014-07-07-04:00</recruitmentStatusDate>
        <localTrialIdentifier>1236</localTrialIdentifier>
        <programCode></programCode>
        <openedForAccrual>2014-07-07-04:00</openedForAccrual>
        <investigator>
            <person>
                <existingPerson>
                    <poID>943919</poID>
                </existingPerson>
            </person>
            <role>Principal Investigator</role>
            <primaryContact>false</primaryContact>
        </investigator>
        <organization>
            <existingOrganization>
                <poID>120807</poID>
            </existingOrganization>
        </organization>
    </site>
    <site>
        <recruitmentStatus>Enrolling by Invitation</recruitmentStatus>
        <recruitmentStatusDate>2014-05-29-04:00</recruitmentStatusDate>
        <localTrialIdentifier>ganesh</localTrialIdentifier>
        <programCode>123459</programCode>
        <openedForAccrual>2014-05-29-04:00</openedForAccrual>
        <investigator>
            <person>
                <existingPerson>
                    <poID>27658186</poID>
                </existingPerson>
            </person>
            <role>Principal Investigator</role>
            <primaryContact>false</primaryContact>
        </investigator>
        <organization>
            <existingOrganization>
                <poID>38249</poID>
            </existingOrganization>
        </organization>
    </site>
    <site>
        <recruitmentStatus>In Review</recruitmentStatus>
        <recruitmentStatusDate>2014-06-09-04:00</recruitmentStatusDate>
        <localTrialIdentifier>mm</localTrialIdentifier>
        <investigator>
            <person>
                <existingPerson>
                    <poID>3114680</poID>
                </existingPerson>
            </person>
            <role>Principal Investigator</role>
            <primaryContact>false</primaryContact>
        </investigator>
        <organization>
            <existingOrganization>
                <poID>120748</poID>
            </existingOrganization>
        </organization>
    </site>
</sites>

  • No labels