How Can We Help?

Pure API Guide: Collaboration Map from the Pure PortalPure API Guide: Collaboration Map from the Pure Portal

This guide demonstrates how users can replicate insights commonly available in Pure’s Reporting workspace or Pure Admin Editor Workspace, in this example is Collaboration map from Pure Portal specifically by identifying external organizations collaborating on research projects and their associated research outputs. Using Pure API endpoints, this guide illustrates how to retrieve and analyze external organizations, their dependent projects, and research outputs.

The focus is on guiding users through the API calls, interpreting hierarchical data, and applying client-side processing to achieve insights similar to those found in Pure Reporting example workspaces. This approach complements the built-in reporting engine by offering additional flexibility for customized data analysis and integration, especially when working with external tools or systems.

Requirements

This guide is intended for users with intermediate experience working with the Pure API. It assumes familiarity with API concepts such as pagination, UUIDs, and JSON response structures.

A valid API key with access to /external-organizations and /dependents endpoints is required.
The API key must be linked to an appropriate access definition with sufficient data visibility.
For setup instructions, refer to the Pure API: Access definitions for content and field filtering
Knowledge of post-processing tools (e.g., Power BI, Excel, Python, etc.) to transform and sort output if needed.

API Endpoints Used

GET /external-organizations?size={page_size}&offset={offset}
GET /external-organizations/{uuid}/dependents
GET /external-organizations/{uuid}

Data Retrieval Workflow

1. Retrieve External Organizations in Pages

Use the paginated endpoint GET /external-organizations with parameters for page size and offset.
Retrieve batches of external organizations until no further items are returned.

2. For Each External Organization, Retrieve Dependents

Query the dependents of the organization using GET /external-organizations/{uuid}/dependents.
Filter dependents by their systemName property to identify:
- Projects (systemName == "Project")
- Research Outputs (systemName == "ResearchOutput")

3. Skip Organizations without Relevant Dependents

Organizations with no project or research output dependents are excluded from further processing to focus analysis on active collaborators.

4. Retrieve Full Organization Details

For each relevant organization, query GET /external-organizations/{uuid} to fetch detailed fields such as:
- Organization name (name.en_US) or name.en_GB)
- Country (address.country.term.en_US) or (address.country.term.en_GB)
- Subdivision (address.subdivision.term.en_US) or (address.subdivision.term.en_GB)
- Geospatial location (address.geoLocation.point)

Post-Processing Logic

The Pure API provides raw structured data but does not calculate aggregated metrics such as counts or rankings. These computations are performed client-side by:

Counting the number of associated projects and research outputs per organization.
Filtering out organizations with zero relevant dependents.
Sorting organizations by the number of associated projects to highlight the most active collaborators.

Users may use any tool or programming language (Python, Power BI, Excel, etc.) to:

Store the processed data in CSV or other formats.
Perform further grouping, ranking, or visualization.
Integrate insights into internal dashboards or reporting tools.

Example Output Structure

Each record includes:

Field	Description
UUID	Unique identifier of the external organization.
Name	Organization's name in English (en_US locale).
Country	Country of the organization’s address.
Subdivision	Administrative subdivision (state/province).
Geospatial Point	Coordinates or geo-location data.
Number of Projects	Count of associated research projects.
Number of Research Outputs	Count of associated research outputs.

Data Validation

To ensure consistency, compare API results (e.g., total research outputs, gender counts) with values shown in Pure Admin or Reporting Workspaces.

This helps confirm:

API data is correctly interpreted
Filtering logic aligns with internal reports

In this collaboration map, some variation between API data and Reporting results may occur due to differences in filters, access permissions, or visibility settings applied by each system. These differences are expected and reflect the specific design and configurations.

Practical Notes

Pagination: The API uses size and offset parameters for pagination. Continuously fetch pages until an empty page is returned.
Concurrent Requests: Parallelize dependent queries for efficiency, respecting API rate limits.
Error Handling: Handle API errors gracefully and log issues to enable retry or debugging.
Locale Awareness: Fields like names and terms are localized. Adjust locale codes if necessary (e.g., en_GB, en_US).
Data Completeness: Some organizations may lack certain address or geospatial data fields.
Filtering: Only organizations with at least one related project or research output are included in the final analysis.

Permissions and Data Access

Data returned depends on your API key’s access level and the roles assigned in Pure. Some organizations or projects may be invisible if your API key lacks the necessary permissions.

Summary

This approach empowers users to uncover key collaboration insights by:

Retrieving comprehensive external organization data.
Associating dependent projects and research outputs.
Applying client-side logic to calculate meaningful metrics and identify key collaborators.

While Pure’s internal reporting modules automate such aggregations, this method offers the flexibility to extract raw data and customize analysis workflows for integration with your own business intelligence or research analytics solutions.

Published at June 25, 2025