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 list operations provided by the Person web service.
Operation createPerson
Creates a person record in PO database.
Request Body | createPersonRequest having person element |
---|---|
Response Body | createPersonResponse having person element |
Sample Request | |
Sample Response | |
Exception Messages | Example: "ID" is present in the request. Example: Address is not present in the request. Example: Invalid email and phone number present in the request. |
Operation updatePerson
Updates an existing person record in PO database.
Request Body | updatePersonRequest having person element. |
---|---|
Response Body | updatePersonResponse having person element. |
Sample Request | |
Sample Response | |
Exception Messages | Example: The person is not found in the database. Example: "ID" is not present in the request. Example: Address is not present in the request. Example: Invalid email is present in the request. |
Operation changePersonStatus
Changes the status of an existing person record.
Request Body | changePersonStatusRequest having personID and status element. |
---|---|
Response Body | changePersonStatusResponse having person element. |
Sample Request | |
Sample Response | |
Exception Messages | Example: Person is not found in the database. Example: Invalid status is present in the request. Example: Person ID is not present in the request. Example: Invalid status transition. |
Operation getPerson
Gets the person record by its database ID.
Request Body | getPersonRequest having personID |
---|---|
Response Body | getPersonResponse having person element. |
Sample Request | |
Sample Response | |
Exception Messages | Example: Person is not found in the database. Example: Person ID is not present in the request. |
Operation getPersonsByCtepId
Gets the person records for the given CTEP ID.
Request Body | getPersonsByCtepIdRequest having ctepID |
---|---|
Response Body | getPersonsByCtepIdResponse having personList (which is unbounded list of person) |
Sample Request | |
Sample Response | |
Exception Messages | Example: No person found for the given CTEP ID. Example: CTEP ID is not present in the request. |
Operation searchPersons
Searches person records.
Request Body | searchPersonsRequest having personSearchCriteria element. |
---|---|
Response Body | searchPersonsResponse having personSearchResultList (which is unbounded list of personSearchResult) |
Sample Request | Example: Search for a person by the first name "Rohit." Example: Search for a person by Last Name, offset, and limit. Example: Search for a person by city. |
Sample Response | Example: Response for a person by the first name "Rohit." |
Exception Messages | Example: Search criteria are not specified. Example: No matching record found. |
Operation createPersonRole
Creates a person role.
Request Body | createPersonRoleRequest having personRole element. |
---|---|
Response Body | createPersonRoleResponse having personRole element. |
Sample Request | Example: Create a Healthcare Provider |
Sample Response | |
Exception Messages | Example: The person is not found in the database. Example: Organization is not found in the database. Example: Organization ID is not present in the request. |
Operation updatePersonRole
Updates an existing person role.
Request Body | updatePersonRoleRequest having personRole element. |
---|---|
Response Body | updatePersonRoleResponse having personRole element. |
Sample Request | |
Sample Response | |
Exception Messages | Example: "ID" is not present in the request. Example: Person Role is not found in the database. Example: Person is not found in the database. |
Operation changePersonRoleStatus
Changes the status of an existing person role.
Request Body | changePersonRoleStatusRequest having roleType, personRoleID, and status. |
---|---|
Response Body | changePersonRoleStatusResponse having personRole element. |
Sample Request | Example: Change the status of a Healthcare Provider role. Example: Change the status of a Clinical Research Staff role. |
Sample Response | |
Exception Messages | Example: Person Role for the given ID is not found in the database. Example: Invalid transition. Example: Invalid status is present in the request. |
Operation getPersonRolesByPersonId
Gets the person roles for a given person ID.
Request Body | getPersonRolesByPersonIdRequest having personID |
---|---|
Response Body | getPersonRolesByPersonIdResponse having personRoleList (which is unbounded list of personRole). |
Sample Request | |
Sample Response | |
Exception Messages | Example: Person is not found in the database. Example: Person ID is not present in the request. Example: Person does not have a Person Role. |
Operation getPersonRoleById
Gets the person role by ID.
Request Body | getPersonRoleByIdRequest having roleType and personRoleID. |
---|---|
Response Body | getPersonRoleByIdResponse having personRole element. |
Sample Request | Example: Get a Healthcare Provider. |
Sample Response | |
Exception Messages | Example: Role for the given Type and ID is not found in the database. Example: Invalid RoleType is specified. Example: Person Role ID is not specified in the request. |
Organization Service
The following sections list operations provided by the Organization web service.
Operation createOrganization
Creates an organization record in the PO database.
Request Body | createOrganizationRequest having organization element. |
---|---|
Response Body | createOrganizationResponse having organization element. |
Sample Request | |
Sample Response | |
Exception Messages | Example: "ID" is present in the request. Example: Address is not present in the request. Example: Invalid phone number is present in the request. |
Operation updateOrganization
Updates an existing organization record for a given organization ID.
Request Body | updateOrganizationRequest having organization element. |
---|---|
Response Body | updateOrganizationResponse having organization element. |
Sample Request | |
Sample Response | The updated organization name is added as an alias (not part of response - but search will return this alias). |
Exception Messages | Example: Organization is not found in the database. Example: "ID" is not present in the request. Example: Address is not present in the request. Example: Invalid email is present in the request. |
Operation getOrganization
Gets the organization record by organization database ID.
Request Body | getOrganizationRequest having organizationID. |
---|---|
Response Body | getOrganizationResponse having organization element. |
Sample Request | |
Sample Response | |
Exception Messages | Example: Organization is not found in the database. Example: Organization ID is not present in the request. |
Operation searchOrganizations
Searches organization records.
Request Body | searchOrganizationsRequest having organizationSearchCriteria element. |
---|---|
Response Body | searchOrganizationsResponse having organizationSearchResultList (which is unbounded list of organizationSearchResult) |
Sample Request | Example: Search organizations by the name "Mayo: (with offset and limit; and searchAliases is TRUE. Also inclludes a search by alias. Example: Search the organizations on the basis of City and State:
|
Sample Response | Search result for the Organizations having name like Mayo: |
Exception Messages | Example: Search criteria are not specified. Example: No matching record found. |
Operation createOrganizationRole
Creates an organization role.
Request Body | createOrganizationRoleRequest having organizationRole element. |
---|---|
Response Body | createOrganizationRoleResponse having organizationRole element. |
Sample Request | Example: Creating a Health CareFacility. Sample request for creating a OversightCommittee: |
Sample Response | Sample response for create HealthCareFacility: |
Exception Messages | Example: Organization is not found in the database (during creation of ResearchOrganization). Example: Organization ID is not present in the request. |
Operation updateOrganizationRole
Updates an existing organization role for a given type and ID.
Request Body | updateOrganizationRoleRequest having organizationRole element. |
---|---|
Response Body | updateOrganizationRoleResponse having organizationRole element. |
Sample Request | Example: Update a Healthcare Facility. |
Sample Response | Sample response for update HealthCareFacility: |
Exception Messages | Example: "ID" is not present in the request. Example: Organization Role is not found in the database. Example: Organization is not found in the database. |
Operation changeOrganizationRoleStatus
Changes the status of an existing organization role for a given role type and organization role ID.
Request Body | changeOrganizationRoleStatusRequest having roleType, organizationRoleID and status element. |
---|---|
Response Body | changeOrganizationRoleStatusResponse having organizationRole element. |
Sample Request | Example: Change the status of a HealthcareFacility: Example: Cange the status of an Oversight Committee. |
Sample Response | Sample response for status change of HealthCareFacility: |
Exception Messages | Example: Organization Role for the given ID is not found in the database. Example: Invalid transition. Example: Invalid status is present in the request. |
Operation getOrganizationRolesByOrgId
Gets the organization role by given organization database ID.
Request Body | getOrganizationRolesByOrgIdRequest having organizationID. |
---|---|
Response Body | getOrganizationRolesByOrgIdResponse having organizationRoleList (which is unbounded list of organizationRole). |
Sample Request | |
Sample Response | |
Exception Messages | Example: Organization is not found in the database. Example: Organization has no Organization Roles. Example: Organization ID is not present in the request. |
Operation getOrganizationRolesByCtepId
Gets the organization roles for a given CTEP ID.
Request Body | getOrganizationRolesByCtepIdRequest having ctepID. |
---|---|
Response Body | getOrganizationRolesByCtepIdResponse having organizationRoleList (which is unbounded list of organizationRole). |
Sample Request | |
Sample Response | |
Exception Messages | Example: No Organizational Roles found for the given CTEP ID. Example: CTEP is not specified in the request. |
Operation getOrganizationRoleById
Gets the organization role for a given organization role type and organization role ID.
Request Body | getOrganizationRoleByIdRequest having roleType and organizationRoleID. |
---|---|
Response Body | getOrganizationRoleByIdResponse having organizationRole element. |
Sample Request | Example: Get a Healthcare Facility by its ID. |
Sample Response | Sample response for HealthCareFacility: |
Exception Messages | Example: Role for the given Type and ID is not found in the database. Example: Invalid Role Type is specified. Example: Organization Role ID is not specified in the request. |
Family Service
The following sections list operations provided by the Family web service.
Operation searchFamiliesByName
Searches family records by family name.
Request Body | searchFamiliesByNameRequest having name |
---|---|
Response Body | searchFamiliesByNameResponse having familyList ( which is unbounded list of family) |
Sample Request | |
Sample Response | |
Exception Messages | Example: No matching record found: Example: Family name is not specified in the request. |
Operation searchFamiliesByOrgId
Searches family records by organization ID.
Request Body | searchFamiliesByOrgIdRequest having organizationId. |
---|---|
Response Body | searchFamiliesByOrgIdResponse having familyList ( which is unbounded list of family) |
Sample Request | |
Sample Response | |
Exception Messages | Example: No matching record found. Example: Organization is not found in the database. Example: Organization ID is not specified in the request. |
Operation getFamilyMemberRelationshipsByFamilyId
Gets the family member relationships by family ID.
Request Body | getFamilyMemberRelationshipsByFamilyIdRequest having familyId. |
---|---|
Response Body | getFamilyMemberRelationshipsByFamilyIdResponse having familyMemberRelationshipList ( which is unbounded list of familyMemberRelationship) |
Sample Request | |
Sample Response | |
Exception Messages | Example: Family is not found in the database. Example: Family ID is not specified in the request. |
Operation getFamily
Gets the family record by its ID.
Request Body | GetFamilyRequest having familyId |
---|---|
Response Body | GetFamilyResponse having Family |
Sample Request | |
Sample Response | |
Exception Messages | Example: No family found for the given Family ID. |
Operation getFamilyMember
Gets the family record by its ID.
Request Body | GetFamilyMemberRequest having familyMemberId |
---|---|
Response Body | GetFamilyMemberResponse having FamilyMember |
Sample Request | |
Sample Response | |
Exception Messages | Example: No Family Member found for the given ID: |