NIH | National Cancer Institute | NCI Wiki  

Contents of this Page

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

Person Service

The following sections describe operations provided by the Person web service. The service supports both JSON and XML formats.

Operation createPerson

Creates a person in PO database.

HTTP MethodPOST
URL/person
Request BodyXML/JSON Person
Response BodyXML/JSON Person
HTTP Response Code

Success:

201

  • Response data: person element
  • Description: Details of the created person, along with uri.

Errors:

  • 500. Internal Server Error
    • Description: An exception occurred at the backend.
    • Response Message: Error message in text/plain format.
  • 400. Bad Request
    • Response Message: Error message in text/plain format.
Sample URL and Request Body

URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person

Request Header (for JSON Request):

Content-Type  application/json
Accept        application/json

Body (for JSON Request):

{
   "prefix":"Dr.",
   "firstName":"John",
   "middleName":"M",
   "lastName":"Phillips",
   "suffix":null,
   "address":{
      "line1":"4100 John R Street",
      "line2":"Division of Hematology",
      "city":"Detroit",
      "stateOrProvince":"MI",
      "country":"USA",
      "postalcode":"48201"
   },
   "contact":[
      {
         "value":"philipp@karmanos.org",
         "type":"EMAIL"
      },
      {
         "value":"philipp222@karmanos.org",
         "type":"EMAIL"
      },
      {
         "value":"313-576-9363",
         "type":"PHONE"
      },
      {
         "value":"313-576-8729",
         "type":"FAX"
      }
   ],
   "status":"ACTIVE"
}


Request Header (for XML Request):

Content-Type  application/xml
Accept        application/xml

Body (for XML Request):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<person xmlns="gov.nih.nci.po.webservices.types">
    <status>ACTIVE</status>
    <prefix>Dr.</prefix>
    <firstName>John</firstName>
    <middleName>M</middleName>
    <lastName>Phillips</lastName>
    <address>
        <line1>4100 John R Street</line1>
        <line2>Division of Hematology</line2>
        <city>Detroit</city>
        <stateOrProvince>MI</stateOrProvince>
        <country>USA</country>
        <postalcode>48201</postalcode>
    </address>
    <contact type="EMAIL">philipp@karmanos.org</contact>
    <contact type="EMAIL">philipp222@karmanos.org</contact>
    <contact type="PHONE">313-576-9363</contact>
    <contact type="FAX">313-576-8729</contact>
</person>
Operation updatePerson

Updates an existing person (for given ID) in PO database.

HTTP MethodPUT
URL/person/{id}
Request BodyXML/JSON Person
Response BodyXML/JSON Person
HTTP Response Code

Success:

  • 200
    • Response data: person element
    • Description: Person details after update.
  • Errors:
  • 500. Internal Server Error
    • Description : Exception occured at the backend (except EntityNotFoundException).
    • Response Message: Error message in text/plain format.
  • 400. Bad Request
    • Response Message: Error message in text/plain format.
  • 404.Not Found
    • Description : Person for the given person ID is not found in the database.
    • Response Message: Error message in text/plain format (Person is not found in the database).
Sample URL and Request Body

URL–> https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person/30428

Request Header (for JSON Request):

Content-Type  application/json
Accept        application/json

Body (for JSON Request):

{
   "prefix":"Dr.",
   "firstName":"John",
   "middleName":"M",
   "lastName":"Phillips",
   "suffix":null,
   "address":{
      "line1":"4100 John R Street",
      "line2":"Division of Hematology",
      "city":"Detroit",
      "stateOrProvince":"MI",
      "country":"USA",
      "postalcode":"48201"
   },
   "contact":[
      {
         "value":"philipp@karmanos.org",
         "type":"EMAIL"
      },
      {
         "value":"313-576-9363",
         "type":"PHONE"
      },
      {
         "value":"313-576-8729",
         "type":"FAX"
      }
   ],
   "id":30428,
   "status":"ACTIVE"
}

Request Header (for XML Request):

Content-Type  application/xml
Accept        application/xml

Body (for XML Request):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<person xmlns="gov.nih.nci.po.webservices.types">
    <id>28211183</id>
    <status>ACTIVE</status>
    <prefix>Dr.</prefix>
    <firstName>Josh</firstName>
    <middleName>abc</middleName>
    <lastName>Philip</lastName>
    <address>
        <line1>4100 John R Street</line1>
        <line2>Division of Hematology</line2>
        <city>Detroit</city>
        <stateOrProvince>MI</stateOrProvince>
        <country>USA</country>
        <postalcode>48201</postalcode>
    </address>
    <contact type="EMAIL">philipp@karmanos.org</contact>
    <contact type="EMAIL">philipp222@karmanos.org</contact>
    <contact type="PHONE">313-576-9363</contact>
    <contact type="FAX">313-576-8729</contact>
</person>
Operation changePersonStatus

Changes the status of an existing person (for given ID).

HTTP MethodPUT
URL/person/{id}/status
Request Body

New status string

(text/plain)
Response Body

New status string

(text/plain)
HTTP Response Code

Success:

200

  • Response data: person status string (text/plain).
  • Description: New status of the person (after update).

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend (except EntityNotFoundException).
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: When the person for given person ID is not found in the database.
    • Response Message: Error message in text/plain format (Person is not found in the database).
Sample URL and Request Body

URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person/30428/status

Request Header:

Content-Type  text/plain
Accept        text/plain

Body:

ACTIVE



Operation getPerson

Gets the person by its database ID.

HTTP MethodGET
URL/person/{id}
Request BodyN/A
Response BodyNon-empty XML/JSON Person
HTTP Response Code

Success:

200

  • Response data: person element
  • Description: Person details for the given person ID.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Person for the given person id is not found in the database.
    • Response Message: Error message in text/plain format (Person is not found in the database).
Sample URL and Request Body

URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person/30428

Request Header (for JSON Request):

Accept    application/json

Request Header (for XML Request):

Accept     application/xml
Operation getPersonsByCTEPId

Gets the Persons for the given CTEP id.

HTTP MethodGET
URL/person/ctep/{id}
Request BodyN/A
Response BodyNon-empty XML/JSON Persons
HTTP Response Code

Success:

200

  • Response data: personList element
  • Description: List of the person having given CTEP id.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.

404. Not Found

  • Description: No person in the database for given CTEP id.
  • Response Message: Error message in text/plain format (Person is not found in the database).
Sample URL and Request Body

URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person/ctep/24561

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request):

Accept     application/xml




Operation searchPersons

Searches the persons.

HTTP MethodGET
URL/persons
Request BodyN/A
Response Body

XML/JSON PersonSearchResultList

or empty collection if no person found matching the criteria.
HTTP Response Code

Success:

200

  • Response data: personSearchResultList element
  • Description: The list having personSearchResult matching given search criteria.

Errors:

500. Internal Server Error

  • Description: Exception occured at the backend.
  • Response Message: Error message in text/plain format.
Sample URL and Request Body

Sample URLs:

The URL can have one or more search criteria. The different search criteria are:

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?firstName=Rohit&city=Herndon

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?lastName=Rohit&offset=2&limit=3

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?email=sconcology.net&statusCode=ACTIVE

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?affiliation=Cancer

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?CTEPID=25879

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?id=28228758

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?countryCode=USA&hasPendingCrsRoles=true&hasPendingHcpRoles=true&hasPendingOcRoles=false

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?countryCode=USA

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?line1=Avenue&line2=2115

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/persons?city=Chicago&stateOrProvince=IL&postalcode=60637

Request Header (for JSON Request):

Accept     application/json

Request Header (for XML Request):

Accept     application/xml
Operation createPersonRole

Creates a personRole.

HTTP MethodPOST
URL/role
Request BodyXML/JSON Person Role
Response BodyXML/JSON Person Role
HTTP Response Code

Success:

200

  • Response data: personRole element
  • Description: Details of the created personRole, along with uri.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 400. Bad Request
    • Response Message: Error message in text/plain format.
Sample URL and Request Body

URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role

Request Header (for JSON Request):

Content-Type  application/json
Accept        application/json

Body (for JSON Request - HealthCareProvider):

{
   "@class":"gov.nih.nci.po.webservices.types.HealthCareProvider",
   "license":null,
   "status":"PENDING",
   "organizationId":120807,
   "address":[
      {
         "line1":"330 Brookline Avenue",
         "line2":"Division East Campus KS 121",
         "city":"Boston",
         "stateOrProvince":"MA",
         "country":"USA",
         "postalcode":"02215"
      }
   ],
   "contact":[
      {
         "value":"davigan@bidmc.harvard.edu",
         "type":"EMAIL"
      },
      {
         "value":"617-667-9925",
         "type":"PHONE"
      },
      {
         "value":"617-667-9922",
         "type":"FAX"
      }
   ],
   "personId":28273761
}

Note-> The body for ClinicalResearchStaff and OrganizationalContact will have respective @Class and other attributes.

Request Header (for XML Request):

Content-Type  application/xml
Accept        application/xml

Body (for XML Request):

1) Sample request for Create OrganizationalContact: 

<personRole xmlns="gov.nih.nci.po.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="OrganizationalContact">
    <status>PENDING</status>
    <organizationId>55334</organizationId>
    <address>
        <line1>330 Brookline Avenue</line1>
        <line2>
            Hematology and Oncology Division East Campus KS 121
        </line2>
        <city>Boston</city>
        <stateOrProvince>MA</stateOrProvince>
        <country>USA</country>
        <postalcode>02215</postalcode>
    </address>
    <contact type="EMAIL">davigan@bidmc.harvard.edu</contact>
    <contact type="PHONE">617-667-9925</contact>
    <contact type="FAX">617-667-9922</contact>
    <personId>55295</personId>
    <title>some title</title>
    <type>IRB</type>
</personRole>

2) Sample request for Create HealthCareProvider:

<personRole xmlns="gov.nih.nci.po.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="HealthCareProvider">
    <status>ACTIVE</status>
    <organizationId>120807</organizationId>
    <address>
        <line1>330 Brookline Avenue</line1>
        <line2>
            Hematology and Oncology Division East Campus KS 121
        </line2>
        <city>Boston</city>
        <stateOrProvince>MA</stateOrProvince>
        <country>USA</country>
        <postalcode>02215</postalcode>
    </address>
    <contact type="EMAIL">davigan@bidmc.harvard.edu</contact>
    <contact type="PHONE">617-667-9925</contact>
    <contact type="FAX">617-667-9922</contact>
    <personId>28260719</personId>
</personRole>
Operation updatePersonRole

Updates an existing personRole for given type and id.

HTTP MethodPUT
URL/role/{type}/{id}
Request BodyXML/JSON Person Role
Response BodyXML/JSON Person Role
HTTP Response Code

Success:

200

  • Response data : personRole element
  • Description: PersonRole details after update.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 400. Bad Request
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: personRole for the given personrole type and id is not found in the database.
    • Response Message: Error message in text/plain format((PersonRole is not found in the database).
Sample URL and Request Body

URL (for updating OrganizationalContact): https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/OrganizationalContact/28210749

Request Header (for JSON Request):

Content-Type  application/json
Accept        application/json

Body (for JSON Request - OrganizationalContact):

{
   "@class":"gov.nih.nci.po.webservices.types.OrganizationalContact",
   "title":"some title",
   "type":"IRB",
   "id":28210749,
   "status":"PENDING",
   "organizationId":28210712,
   "address":[
      {
         "line1":"330 Brookline Avenue",
         "line2":null,
         "city":"Boston",
         "stateOrProvince":"MA",
         "country":"USA",
         "postalcode":"02215"
      }
   ],
   "contact":[
      {
         "value":"wstock@medicine.bsd.uchicago.edu",
         "type":"EMAIL"
      },
      {
         "value":"773-834-7425",
         "type":"PHONE"
      },
      {
         "value":"773-702-0963",
         "type":"FAX"
      }
   ],
   "personId":28210667
}

URL (for updating ClinicalResearchStaff): https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/ClinicalResearchStaff/28211370

URL (for updating HealthCareProvider): https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/HealthCareProvider/28211370

Note-> The body for ClinicalResearchStaff and HealthCareProvider will have respective @Class and other attributes.


Request Header (for XML Request):

Content-Type  application/xml
Accept        application/xml

Body (for XML Request - HealthCareProvider):

<personRole xmlns="gov.nih.nci.po.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="HealthCareProvider">
    <id>28211370</id>
    <status>PENDING</status>
    <organizationId>120807</organizationId>
    <address>
        <line1>330 Brookline Avenue</line1>
        <line2>
            Hematology and Oncology Division East Campus KS 121
        </line2>
        <city>Boston</city>
        <stateOrProvince>MA</stateOrProvince>
        <country>USA</country>
        <postalcode>02215</postalcode>
    </address>
    <contact type="EMAIL">davigan@bidmc.harvard.edu</contact>
    <contact type="PHONE">617-667-9925</contact>
    <contact type="FAX">617-667-9922</contact>
    <personId>28211331</personId>
</personRole>
Operation changePersonRoleStatus

Changes the status of an existing personrole for given type and id.

HTTP MethodPUT
URL/role/{type}/{id}/status
Request Body

New status string

(text/plain)
Response Body

New status string

(text/plain)
HTTP Response Code

Success:

200

  • Response data: personRole status string (text/plain)
  • Description: New status of the personRole (after update).

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: When the personRole for given personRole type and id is not found in the database.
    • Response Message: Error message in text/plain format (PersonRole is not found in the database).
Sample URL and Request Body

URL (for changing OrganizationalContact status):

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/ClinicalResearchStaff/9558371/status

Request Header:

Content-Type  text/plain
Accept        text/plain

Body:

INACTIVE

URL (for changing HealthCareProvider status):

https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/HealthCareProvider/269797/status

Operation getPersonRolesByPersonId

Gets the personRoles for given person id.

HTTP MethodGET
URL/person/{id}/roles
Request BodyN/A
Response BodyXML/JSON PersonRoles or empty collection if no roles for the person id
HTTP Response Code

Success:

200

Response data: personRoleList element

Description: List of personRole for given Person id.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: When a person for the given person id is not found in the database.
    • Response Message: Error message in text/plain format(Person is not found in the database).
Sample URL and Request Body

URL: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/person/269790/roles

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request):

Accept     application/xml



Operation getPersonRoleById

Gets the personRole for given role type and id.

HTTP MethodGET
URL

/role/{type}/{id}

Request BodyN/A
Response BodyNon-empty XML/JSON PersonRole
HTTP Response Code

Success:

200

Response data: personRole element

Description: PersonRole details for the given personRole type and id.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: When the personRole for the given personRole type and id is not found in the database.
    • Response Message: Error message in text/plain format (PersonRole is not found in the database).
Sample URL and Request Body

Sample URLs:

For HealthCareProvider-> https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/HealthCareProvider/269797

For ClinicalResearchStaff: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/ClinicalResearchStaff/9558371

For OrganizationalContact: https://trials.nci.nih.gov/po-webservices/services/person-rest-service/role/OrganizationalContact/9558371

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request):

Accept      application/xml

Organization Service

The following sections describe operations provided by the Organization web service.

Operation createOrganization

Creates an Organization in PO database.

HTTP MethodPOST
URL/organization
Request BodyXML/JSON Organization
Response BodyXML/JSON Organization
HTTP Response Code

Success:

HTTP Response : 201

Response data : organization element

Description: Details of the created Organization, along with uri.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 400. Bad Request
    • Response Message: Error message in text/plain format.
Sample URL and Request Body (XML Format)

URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organization

Request Header (for JSON Request):

Content-Type  application/json
Accept        application/json

Body (for JSON Request):

{
   "name":"Mayo Clinic Test",
   "address":{
      "line1":"200 First Street Southwest",
      "line2":"Test",
      "city":"Rochester",
      "stateOrProvince":"MN",
      "country":"USA",
      "postalcode":"55905"
   },
   "contact":[
      {
         "value":"mayo.test@mail.nih.gov",
         "type":"EMAIL"
      },
      {
         "value":"111-222-3333",
         "type":"PHONE"
      },
      {
         "value":"111-222-3344",
         "type":"FAX"
      },
      {
         "value":"111-222-3355",
         "type":"TTY"
      },
      {
         "value":"http://www.mayoclinic.org",
         "type":"URL"
      }
   ],
   "status":"PENDING"
}


Request Header (for XML Request):

Content-Type  application/xml
Accept        application/xml

Body (for XML Request):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<organization xmlns="gov.nih.nci.po.webservices.types">
    <status>PENDING</status>
    <name>Mayo Clinic Test</name>
    <address>
        <line1>200 First Street Southwest</line1>
        <line2>Test</line2>
        <city>Rochester</city>
        <stateOrProvince>MN</stateOrProvince>
        <country>USA</country>
        <postalcode>55905</postalcode>
    </address>
    <contact type="EMAIL">mayo.test@mail.nih.gov</contact>
    <contact type="PHONE">111-222-3333</contact>
    <contact type="FAX">111-222-3344</contact>
    <contact type="TTY">111-222-3355</contact>
    <contact type="URL">http://www.mayoclinic.org</contact>
</organization>
Operation updateOrganization

Updates an existing Organization for given organization id.

HTTP MethodPUT
URL/organization/{id}
Request BodyXML/JSON Organization
Response BodyXML/JSON Organization
HTTP Response Code

Success:

200

  • Response data: organization element
  • Description: Organization details after update.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 400. Bad Request
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Organization for the given organization id is not found in the database.
    • Response Message: Error message in text/plain format (Organization is not found in the database).

NOTE : The updated organization name is added as an alias (not part of response). However a search will return this alias.



Sample URL and Request Body (XML Format)

URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organization/28227601

Request Header (for JSON Request):

Content-Type  application/json
Accept        application/json

Body (for JSON Request):

{
   "name":"Mayo Clinic Test",
   "address":{
      "line1":"200 First Street Southwest",
      "line2":"Test updated line",
      "city":"Rochester",
      "stateOrProvince":"MN",
      "country":"USA",
      "postalcode":"55905"
   },
   "contact":[
      {
         "value":"mayo.test@mail.nih.gov",
         "type":"EMAIL"
      },
      {
         "value":"111-222-3333",
         "type":"PHONE"
      },
      {
         "value":"111-222-3344",
         "type":"FAX"
      },
      {
         "value":"111-222-3355",
         "type":"TTY"
      },
      {
         "value":"http://www.mayoclinic.org",
         "type":"URL"
      }
   ],
   "id":28210629,
   "status":"PENDING"
}


Request Header (for XML Request): 

Content-Type  application/xml
Accept        application/xml

Body (for XML Request): 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<organization xmlns="gov.nih.nci.po.webservices.types">
    <id>28227601</id>
    <status>PENDING</status>
    <name>Mayo Clinic Test2</name>
	<address>
        <line1>200 First Street Southwest</line1>
        <line2>Test</line2>
        <city>Rochester</city>
        <stateOrProvince>MN</stateOrProvince>
        <country>USA</country>
        <postalcode>55905</postalcode>
    </address>
    <contact type="EMAIL">mayo.test@mail.nih.gov</contact>
    <contact type="PHONE">111-222-3333</contact>
    <contact type="FAX">111-222-3344</contact>
    <contact type="TTY">111-222-3355</contact>
    <contact type="URL">http://www.mayoclinic.org</contact>
</organization>

Operation getOrganization

Gets the Organization on the basis of organization (database) id.

HTTP MethodGET
URL/organization/{id}
Request BodyN/A
Response BodyNon-empty XML/JSON Organization
HTTP Response Code

Success:

200

  • Response data: organization element
  • Description: Organization details for the given organization id.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Organization for the given organization id is not found in the database.
    • Response Message: Error message in text/plain format (Organization is not found in the database).
Sample URL and Request Body (XML Format)

URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organization/28227567

Request Header (for JSON Request):


Accept     application/json

Request Header (for XML Request):

Accept     application/xml
Operation searchOrganizations

Searches the Organizations.

HTTP MethodGET
URL/organizations
Request BodyN/A
Response Body

Success:

200

  • Response data: organizationSearchResultList element
  • Description: List of organizationSearchResult matching given search criteria.

Errors:

500. Internal Server Error

  • Description: Exception occured at the backend.
  • Response Message: Error message in text/plain format.

**Note

  • When specifying boolean fields like hasPendingRoRoles, the value true is accepted while false is ignored during search. This is similar to the behavior is UI where false/0 is equal to not specifying/selecting that field.
  • When searching Organizations using CTEP ID, search for the IO CTEP IDs separately from HCF and RO CTEP IDs.
  • The searchResult contains aliases in the response. They are NOT part of create/update or request/response.
HTTP Response Code

Sample URLs:

The URL can have one or more search criteria. The different search criteria are:

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?organizationName=Mayo&statusCode=ACTIVE

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?CTEPID=AZ020

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?id=140392

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?familyName=cancer&hasChangeRequest=true

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?hasPendingHcfRoles=true&searchAliases=true

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?line1=Avenue&city=Birmingham&stateOrProvince=AL&countryCode=USA

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?line2=Floor&postalcode=10010

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?organizationName=Mayo&offset=10&limit=4

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request): 

Accept     application/xml
Sample URL and Request Body (XML Format)

Sample URLs:

The URL can have one or more search criteria. The different search criteria are:

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?organizationName=Mayo&statusCode=ACTIVE

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?CTEPID=AZ020

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?id=140392

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?familyName=cancer&hasChangeRequest=true

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?hasPendingHcfRoles=true&searchAliases=true

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?line1=Avenue&city=Birmingham&stateOrProvince=AL&countryCode=USA

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?line2=Floor&postalcode=10010

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organizations?organizationName=Mayo&offset=10&limit=4

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request): 

Accept     application/xml
Operation createOrganizationRole

Creates an OrganizationRole.

HTTP MethodPOST
URL/role
Request BodyXML/JSON OrganizationRole
Response BodyXML/JSON OrganizationRole
HTTP Response Code

Success:

201

  • Response data: organizationRole element
  • Description: Details of the created organizationRole, along with uri.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 400. Bad Request
    • Response Message: Error message in text/plain format.
Sample URL and Request Body (XML Format)

URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/role

Request Header (for JSON Request):

Content-Type  application/json
Accept        application/json

Body (for JSON Request - HealthCareFacility):

{
   "@class":"gov.nih.nci.po.webservices.types.HealthCareFacility",
   "name":"University of Toronto",
   "status":"PENDING",
   "organizationId":28210705,
   "address":[
      {
         "line1":"University of Toronto",
         "line2":null,
         "city":"Toronto",
         "stateOrProvince":"Ontario",
         "country":"CAN",
         "postalcode":"M5S 1A1"
      }
   ],
   "contact":[
   ]
}


Request Header (for XML Request): 

Content-Type  application/xml
Accept 	      application/xml

Body (for XML Request):

For creating a HealthCareFacility:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<organizationRole xmlns="gov.nih.nci.po.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="HealthCareFacility">
    <status>PENDING</status>
    <organizationId>28210543</organizationId>
    <address>
        <line1>University of Toronto</line1>
        <city>Toronto</city>
        <stateOrProvince>Ontario</stateOrProvince>
        <country>CAN</country>
        <postalcode>M5S 1A1</postalcode>
    </address>
    <name>University of Toronto</name>
</organizationRole>

For creating a OversightCommittee:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<organizationRole xmlns="gov.nih.nci.po.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="OversightCommittee">
    <status>ACTIVE</status>
    <organizationId>28210543</organizationId>
    <address>
        <line1>University of Toronto</line1>
        <city>Toronto</city>
        <stateOrProvince>Ontario</stateOrProvince>
        <country>CAN</country>
        <postalcode>M5S 1A1</postalcode>
    </address>
    <contact type="EMAIL">mayo.test@mail.nih.gov</contact>
    <type>Research Ethics Board</type>
</organizationRole>
Operation updateOrganizationRole

Updates an existing OrganizationRole (for given type and id).

HTTP MethodPUT
URL/role/{type}/{id}
Request BodyXML/JSON OrganizationRole
Response BodyXML/JSON OrganizationRole
HTTP Response Code

Success:

200

  • Response data: organizationRole element
  • Description: organizationRole details after update.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 400. Bad Request
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Organization for the given organization id is not found in the database.
    • Response Message: Error message in text/plain format (Organization is not found in the database).
Sample URL and Request Body (XML Format)

URL for updating a HealthCareFacility–>

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/role/HealthCareFacility/28211370

Request Header (for JSON Request):

Content-Type  application/json
Accept        application/json

Body (for JSON Request):

    {
       "@class": "gov.nih.nci.po.webservices.types.HealthCareFacility",
       "name": "University of Toronto",
       "id": 28210742,
       "status": "PENDING",
       "organizationId": 28210705,
       "address":
       [
           {
               "line1": "University of Toronto",
               "line2": null,
               "city": "Toronto",
               "stateOrProvince": "Ontario",
               "country": "CAN",
               "postalcode": "M5S 1A1"
           }
       ],
       "contact":
       [
       ]
    }


Request Header (for XML Request):

Content-Type  application/xml
Accept 	      application/xml

Body (for XML Request)–>

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<organizationRole xmlns="gov.nih.nci.po.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="HealthCareFacility">
    <id>28227678</id>
    <status>PENDING</status>
    <organizationId>7331</organizationId>
    <address>
        <line1>University of Toronto</line1>
        <city>Toronto</city>
        <stateOrProvince>Ontario</stateOrProvince>
        <country>CAN</country>
        <postalcode>M5S 1A1</postalcode>
    </address>
    <name>University of Toronto</name>
</organizationRole>
Operation changeOrganizationRoleStatus

Changes the status of an existing OrganizationRole (for given type and id).

HTTP MethodPUT
URL/role/{type}/{id}/status
Request Body

New status string

(text/plain)
Response Body

New status string

(text/plain)
HTTP Response Code

Success:

200

  • Response data: organizationRole status string (text/plain)
  • Description: New status of the organizationRole (after update).

Errors:

  • 500. Internal Server Error

    • Description: Exception occured at the backend.

    • Response Message: Error message in text/plain format.

  • 404
    • Description: organizationRole for given organizationRole type and id is not found in the database.
    • Response Message: Error message in text/plain format (OrganizationRole is not found in the database).
Sample URL and Request Body (XML Format)

URL for changing HealthCareFacility status:

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/role/HealthCareFacility/7335/status

Request Header:

Content-Type  text/plain
Accept 	      text/plain

Body:

INACTIVE


URL for changing ResearchOrganization status:

https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/role/ResearchOrganization/24108193/status

Operation getOrganizationRolesByOrgId

Gets the OrganizationRole for the given organization database id.

HTTP MethodGET
URL/organization/{id}/roles
Request BodyN/A
Response BodyXML/JSON OrganizationRoles or empty collection if no roles for the organization
HTTP Response Code

Success:

200

  • Response data: organizationRoleList element.
  • Description: List of organizationRole for given Organization id.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Organization for the given organization id is not found in the database.
    • Response Message: Error message in text/plain format (Organization is not found in the database).
Sample URL and Request Body (XML Format)

URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organization/269790/roles

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request):

Accept 	 application/xml
Operation getOrganizationRolesByCTEPId

Gets the OrganizationRoles for the given CTEP id.

HTTP MethodGET
URL/organization/ctep/{id}
Request BodyN/A
Response BodyNon-empty XML/JSON OrganizationRoles
HTTP Response Code

Success:

200

  • Response data: organizationRoleList element
  • Description: List of organizationRole for given CTEP ID.

Errors:

200

  • Response data: organization element
  • Description: Organization details after update.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Organization for the given organization id is not found in the database.
    • Response Message: Error message in text/plain format (Organization is not found in the database).
Sample URL and Request Body (XML Format)

URL: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/organization/ctep/11030

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request):

Accept 	  application/xml
Operation getOrganizationRoleById

Gets the OrganizationRole (for given organization role type and id).

HTTP MethodGET
URL/role/{type}/{id}
Request BodyN/A
Response BodyNon-empty XML/JSON OrganizationRole
HTTP Response Code

Success:

200

  • Response data: organizationRole element
  • Description: organizationRole details for the given organizationRole type and id.

Errors:

200

  • Response data: organization element
  • Description: Organization details after update.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: organizationRole for the given organizationRole type and id is not found in the database.
    • Response Message: Error message in text/plain format (OrganizationRole is not found in the database).
Sample URL and Request Body (XML Format)

Sample URLs:

For HealthCareFacility: https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/role/HealthCareFacility/7335

For ResearchOrganization:
https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/role/ResearchOrganization/24108193

For OversightCommittee:
https://trials.nci.nih.gov/po-webservices/services/organization-rest-service/role/OversightCommittee/25124222

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request):

Accept 	  application/xml

Family Service

The following sections describe operations provided by the Family web service.

Operation searchFamilies

Searches the families on the basis of Family name and/or organizationId. If URL has both family name and organizationId, then the result will be the intersection of the two search results.

HTTP MethodGET
URL/families
Request BodyN/A
Response Body

XML/JSON FamilyList

or empty collection if no family found for the given name(if specified) or organizationId(if specified).

or exception if organizationId is specified but no organization found of the given organizationId.

HTTP Response Code

Success:

HTTP Response : 200

Response data : familyList element

Description: The list having family matching given search criteria.

Errors:

  • 500. Internal Server Error
    • Description: Exception occurred at the backend (except EntityNotFoundException).
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Organization for the given organizationId is not found in the database.
    • Response Message: Error message in text/plain format.
Sample URL

Sample URLs–>

https://trials.nci.nih.gov/po-webservices/services/family-rest-service/families?name=cancer

https://trials.nci.nih.gov/po-webservices/services/family-rest-service/families?organizationId=213820

https://trials.nci.nih.gov/po-webservices/services/family-rest-service/families?name=cancer&organizationId=149221 (both present in search criteria)

https://trials.nci.nih.gov/po-webservices/services/family-rest-service/families (search criteria blank)

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request):

Accept        application/xml
Operation getFamilyMemberRelationshipsByFamilyId

Gets the FamilyMemberRelationships on the basis of familyId.

HTTP MethodGET
URL/familyMemberRelationships
Request BodyN/A
Response Body

XML/JSON FamilyMemberRelationshipList

or empty collection if no familyMemberRelationship found for given familyId.

or exception if family for the given familyId is not found in the database

HTTP Response Code

Success:

HTTP Response : 200

Response data : familyMemberRelationshipList element

Description: The list having familyMemberRelationship matching given search criteria.

Errors:

1. HTTP Response : 500 (Internal Server Error)

Description : When an exception occurs at the backend(except EntityNotFoundException).

Response Message: Error message in text/plain format.

2. HTTP Response : 404 (Not Found)

Description : When the family for the given familyId is not found in the database.

Response Message: Error message in text/plain format.

Sample URL

URL: https://trials.nci.nih.gov/po-webservices/services/family-rest-service/familyMemberRelationships?familyId=16157293

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request):

Accept        application/xml
Operation getFamily

Gets the Family by its ID.

HTTP MethodGET
URL/family/{id}
Request BodyN/A
Response Body

Success:

HTTP Response : 200

Response data : family element

Description: Family for given ID

200

  • Response data: organization element
  • Description: Organization details after update.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Family for the given familyId is not found in the database.
    • Response Message: Error message in text/plain format.
HTTP Response Code

Success:

HTTP Response : 200

Response data : family element

Description: Family for given ID

200

  • Response data: organization element
  • Description: Organization details after update.

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Family for the given familyId is not found in the database.
    • Response Message: Error message in text/plain format.
Sample URL

URL: https://trials.nci.nih.gov/po-webservices/services/family-rest-service/family/33217

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request):

Accept        application/xml
Operation getFamilyMember

Gets the FamilyMember by its ID.

HTTP MethodGET
URL/familymember/{id}
Request BodyNA
Response Body

Success: 200

  • Response data: familyMember element
  • Description: FamilyMember for given id

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Family member for the given ID is not found in the database.
    • Response Message: Error message in text/plain format.
HTTP Response Code

Success: 200

  • Response data: familyMember element
  • Description: FamilyMember for given id

Errors:

  • 500. Internal Server Error
    • Description: Exception occured at the backend.
    • Response Message: Error message in text/plain format.
  • 404. Not Found
    • Description: Family member for the given ID is not found in the database.
    • Response Message: Error message in text/plain format.
Sample URL

URL: https://trials.nci.nih.gov/po-webservices/services/family-rest-service/familymember/13334

Request Header (for JSON Request):

Accept     application/json


Request Header (for XML Request):

Accept        application/xml