Bilateral API — typed result payload surface - PRMS — Planning, Reporting & Management System

The Bilateral API (/api/bilateral/*) is the authoritative typed payload surface for downstream consumers of CGIAR results. It is designed for bilateral funders, discovery portals, and BI dashboards that need stable, readable result data without going through the authenticated PRMS UI. The payload contract is maintained in onecgiar-pr-server/docs/bilateral-result-summaries.en.md; all shape changes must update that file’s change log.

/api/bilateral/* endpoints do not require a JWT. Authentication is enforced at the infrastructure perimeter (API Gateway / IP allowlist), not inside NestJS. Do not send an auth header — it is not read on this surface.

Bilateral endpoints are also exempt from rate throttling. The global 100 req / 60 s throttle does not apply. Volume controls belong at the API Gateway / network layer.

Endpoints

All bilateral routes are mounted under /api/bilateral/.

List all results (paginated)

GET /api/bilateral/list

Returns a paginated, filterable list of active results. Each item carries the type discriminator, result_id, and a fully enriched data object that includes common core fields plus the type-specific summary for the result’s indicator family. Query parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based).
`limit`	integer	`10`	Items per page. Maximum: `500`.
`source`	enum	—	`Result` (W1/W2 funded) or `API` (W3/Bilateral funded).
`portfolio`	string	—	Portfolio acronym, e.g. `P22`, `P25`.
`phase_year`	integer	—	Reporting year, e.g. `2025`.
`result_type`	enum	—	Result type name: `Knowledge product`, `Innovation use`, `Innovation development`, `Capacity sharing for development`, `Policy change`, `Innovation Package`, `Other outcome`, `Other output`, `Impact contribution`.
`status_id`	integer	—	Workflow status id (1–7).
`status`	enum	—	`Editing`, `Quality Assessed`, `Submitted`, `Discontinued`, `Pending Review`, `Approved`, `Rejected`.
`last_updated_from`	ISO 8601 date	—	Filter by last-updated date range start.
`last_updated_to`	ISO 8601 date	—	Filter by last-updated date range end.
`created_from`	ISO 8601 date	—	Filter by created date range start.
`created_to`	ISO 8601 date	—	Filter by created date range end.
`center`	string	—	Leading center code or acronym, e.g. `IRRI`.
`initiative_lead_code`	string	—	Initiative `official_code`; returns results where this initiative is the lead (role 1).
`search`	string	—	Full-text search on result title.

Get a single result

GET /api/bilateral/:id

Returns one result by its numeric result_id. Response shape is identical to a single list entry.

Get all results (sync)

GET /api/bilateral/results

Retrieves all active results for external synchronization. Supports optional query parameters bilateral (boolean — restrict to results with linked bilateral projects) and type (result type discriminator string, e.g. knowledge_product).

Get all results (unfiltered)

GET /api/bilateral

Returns up to limit results (default 10) with no pagination controls. Intended for quick sampling; use /api/bilateral/list for production consumers.

Response shape

The response is a raw array — it is not wrapped in the PRMS response envelope. Each element has the following top-level structure:

type

string

required

Result type discriminator. One of: knowledge_product, capacity_sharing, innovation_development, innovation_use, innovation_package, policy_change. Other types (e.g. other output, other outcome) may appear without a dedicated type-specific summary.

result_id

number

required

Numeric primary key of the result row in PRMS.

data

object

required

Fully enriched result document. Contains common core fields (listed below) plus the type-specific *_summary object for the result’s indicator family.

Common fields on `data`

These fields are present for all or most result types. Identity and lifecycle

data.result_code

number

Stable public-facing numeric code. Used in pdf_link and prms_link URLs.

data.result_title

string

Headline title of the result (bilateral-friendly name).

data.description

string

Long-form description of what was achieved and how.

data.year

number

Reporting year context — which reporting cycle this result belongs to.

data.is_active

boolean

Soft-delete / validity flag. true means the record is current.

data.status_id

number

Numeric workflow status id. See obj_status for the human-readable form.

data.obj_status

object

{ result_status_id, status_name, status_description } — human-readable submission state, e.g. "Submitted".

data.pdf_link

string

URL to the PRMS PDF/report view for this result code.

data.prms_link

string

Deep link into the PRMS web UI full result editor.

data.created_date

string

ISO 8601 timestamp — when this record first entered PRMS.

data.last_updated_date

string

ISO 8601 timestamp — last change to the result.

Indicator family and level

data.result_level

object

{ code, name, description } — where in the results chain this sits (output, outcome, etc.).

data.indicator_category

object

{ code, name } — indicator family for display (e.g. "Innovation use").

Theory of Change and primary initiative

data.toc_alignment

array

Per contributing initiative: entity (official_code, name), initiative_role, toc_results[] with level, sub_entity, and result_name.

data.primary_entity

object

{ official_code, name } — the main initiative that owns or leads this result.

Geography

data.geographic_focus

object

{ code, name, description } — geographic scope type (national, regional, multi-national, etc.).

data.regions

array

Region objects when the result applies to one or more broader geographic areas.

data.countries

array

[{ code, name }] — ISO-style country entries.

Centers and partners

data.contributing_centers

array

[{ code, name, acronym, is_lead }] — CGIAR centers involved; is_lead marks the lead center.

data.leading_result

object

{ lead_kind, id, code, name, acronym } — the lead entity. lead_kind is "center" or "partner". Identifiers use CLARISA ids, not internal PRMS join PKs.

data.contributing_partners

array

Non-CGIAR or additional partners when captured.

data.bilateral_projects

array

Bilateral grant / project summaries tied to this result.

DAC cross-cutting scores

data.dac_scores

object

Object with keys gender, climate_change, nutrition, environmental_biodiversity, poverty. Each: tag_title (significance level text) and impact_area_names[] when applicable.

Evidence and submission

data.evidences

array

[{ link, description }] — proof or references attached to the result.

data.last_submission

object

Present when status_id is 2 (Quality Assessed) or 3 (Submitted): { id, created_date, comment, status, status_id, submitted_by: { user_id, first_name, last_name } }.

data.source

string

Source enum string, e.g. "Result".

data.source_definition

string

Funding / reporting stream label, e.g. "W1/W2".

data.created_by

object

{ first_name, last_name, email } — who created or owns the record in PRMS.

Type-specific summaries

Each result type appends a summary object to data when type matches. Summaries use CLARISA ids for all referenced entities — never internal PRMS join PKs.

`knowledge_product` → `data.knowledge_product_summary`

data.knowledge_product_summary.handle

string

Stable CGSpace / product handle — the only field in this summary. The full result_knowledge_product_array tree is removed during bilateral enrichment and replaced by this slim object.

`innovation_development` → `data.innovation_development_summary`

Covers the innovation profile (typology, readiness level, developers), anticipated user demand, budget lines, and a questionnaire block. Key fields:

data.innovation_development_summary.short_name

string

Short title of the innovation.

data.innovation_development_summary.typology

object

{ id, code, name, definition } — CLARISA innovation type.

data.innovation_development_summary.innovation_readiness_level

object

{ id, level, name, definition } — TRL-style readiness scale.

data.innovation_development_summary.anticipated_user_demand

object

Structured demand without internal ids: actors[], organizations[], measures[].

data.innovation_development_summary.initiative_budget

array

Budget rows: { current_year, next_year, kind_cash, is_determined, initiative: { id, official_code, name } }. initiative.id is the CLARISA initiative id.

data.innovation_development_summary.bilateral_project_budget

array

Budget rows: { in_cash, in_kind, kind_cash, is_determined, project: { id, short_name, full_name } }. project.id is the CLARISA project id.

data.innovation_development_summary.partner_budget

array

Budget rows:

{ kind_cash, in_cash, in_kind, is_determined, institutions_id, institution: { id, name, acronym, institution_type_name } }

. institution.id is the CLARISA institution id.

data.innovation_development_summary.innovation_development_questionnaire

object

Four arrays of { question, question_id, answer, selected_sub_options? }: responsible_innovation_and_scaling, intellectual_property_rights, innovation_team_diversity, megatrends. Megatrends uses answer.selections[] (one entry per checked option). Portfolio P25 uses the V2 question catalog.

`innovation_use` → `data.innovation_use_summary`

Current and 2030 use sections, innovation use level from CLARISA, links to other results, and budget lines (no reference materials or user-need evidence links — those are innovation development only).

data.innovation_use_summary.innovation_use_level

object

{ id, level, name, definition } — evidence-based use level from CLARISA.

data.innovation_use_summary.current_section

object

Populated when innov_use_to_be_determined is false: actors[], organizations[], other_quantitative[] for the reporting year.

data.innovation_use_summary.innovation_use_2030_section

object

Populated when innov_use_2030_to_be_determined is false: same shape as current_section for 2030 projections.

`capacity_sharing` → `data.capacity_development_summary`

data.capacity_development_summary.male_using

number

Male participant count (or null).

data.capacity_development_summary.female_using

number

Female participant count (or null).

data.capacity_development_summary.delivery_method

object

{ name, description } — resolved from the cap dev delivery methods catalog. No raw FK.

data.capacity_development_summary.training_length

object

{ name, term, description } — from the cap dev term catalog (length of training).

data.capacity_development_summary.on_behalf_organizations

array

[{ id, name, acronym, institution_type_name }] — implementing org rows. id is the CLARISA institution id.

`policy_change` → `data.policy_change_summary`

data.policy_change_summary.policy_type

object

{ id, name, definition } — CLARISA policy type.

data.policy_change_summary.policy_stage

object

{ id, name, definition } — CLARISA policy stage.

data.policy_change_summary.amount

number

Policy-related USD amount when applicable, or null.

data.policy_change_summary.amount_status_label

string

"Confirmed", "Estimated", or "Unknown".

[{ parent_question, option_text }] — options ticked under “Is this result related to”. Empty array when none.

data.policy_change_summary.policy_implementing_organizations

array

[{ id, name, acronym, institution_type_name }] — implementing orgs (PRMS role 4). id is the CLARISA institution id.

`innovation_package` → `data.ipsr_pathway_summary`

The four IPSR pathway steps in one object. Any step may be null if its data could not be loaded.

data.ipsr_pathway_summary.step_one

object

Core innovation row, specify_aspired_outcomes_impact, target_innovation_use (actors, organizations, other quantitative), scalig_ambition (note: spelled this way in the payload), and expert workshop participants.

data.ipsr_pathway_summary.step_two

array

Complementary innovation rows. Each item carries official_code (CLARISA initiative code) and result_type_name (human-readable) in place of the internal initiative_id and result_type_id.

data.ipsr_pathway_summary.step_three

object

Scaling readiness assessment: result_core_innovation, result_innovation_package (flags only), optional expert_workshop (assessed during, assessment mode, and conditional workshop_level_assignments), evidence_based_assessment with readiness/use levels per innovation, and target_innovation_use.

data.ipsr_pathway_summary.step_four

object

Slim investments slice: initiative_budget, bilateral_project_budget, partner_budget (same row shape as innovation development / innovation use), ipsr_materials, has_scaling_studies, scaling_studies_urls. Internal audit columns, pictures, and publish flags are omitted.

Payload conventions

Discriminator: always read type to determine which *_summary key is present on data.
Identifiers: all cross-entity references use CLARISA ids (initiative.id, institution.id, project.id), never internal PRMS join PKs.
Field names: camelCase on data and all nested objects.
Array pass-through: the response is a raw array — there is no PRMS envelope (response, statusCode, message wrapper).
Additive changes: new fields are added without versioning. Breaking changes (field removals, renames, type changes) require a v2 rollout.
Null vs absent: missing optional objects are null; missing optional arrays are [].

Reference JSON fragment

The following illustrates a representative data object (values are examples only):

{
  "result_code": 28738,
  "result_title": "Adoption of improved rice varieties in Bangladesh",
  "year": 2025,
  "status_id": 3,
  "obj_status": { "result_status_id": "3", "status_name": "Submitted", "status_description": null },
  "pdf_link": "https://reporting.cgiar.org/reports/result-details/28738?phase=6",
  "prms_link": "https://reporting.cgiar.org/result/result-detail/28738/general-information?phase=6",
  "is_active": true,
  "result_level": { "code": 3, "name": "Outcome", "description": "…" },
  "indicator_category": { "code": 2, "name": "Innovation use" },
  "primary_entity": { "official_code": "SP09", "name": "Scaling for Impact" },
  "geographic_focus": { "code": 3, "name": "Multi-national", "description": "…" },
  "countries": [{ "code": "BD", "name": "Bangladesh" }],
  "contributing_centers": [{ "code": "CENTER-15", "name": "WorldFish", "acronym": "WorldFish", "is_lead": true }],
  "leading_result": { "lead_kind": "center", "id": 12345, "code": "CENTER-15", "name": "WorldFish", "acronym": "WorldFish" },
  "dac_scores": {
    "gender": { "tag_title": "(1) Significant", "impact_area_names": [] },
    "nutrition": { "tag_title": "(2) Principal", "impact_area_names": ["Food Security"] }
  },
  "source": "Result",
  "source_definition": "W1/W2"
}

Change log

All payload changes are tracked in onecgiar-pr-server/docs/bilateral-result-summaries.en.md. Consult that file as the authoritative contract before building a consumer integration. The source implementation is bilateral.service.ts (enrichBilateralResultResponse and related builders).

Bilateral endpoints are ideal for discovery tools, bilateral funder portals, and BI dashboards. They require no API key from PRMS itself — configure access controls at your API Gateway or network layer.

Overview

Results

Reporting Surfaces

Administration

Bilateral API — typed result payload surface

Endpoints

List all results (paginated)

Get a single result

Get all results (sync)

Get all results (unfiltered)

Response shape

Common fields on `data`

Type-specific summaries

`knowledge_product` → `data.knowledge_product_summary`

`innovation_development` → `data.innovation_development_summary`

`innovation_use` → `data.innovation_use_summary`

`capacity_sharing` → `data.capacity_development_summary`

`policy_change` → `data.policy_change_summary`

`innovation_package` → `data.ipsr_pathway_summary`

Payload conventions

Reference JSON fragment

Change log

Build docs developers (and LLMs) love

Overview

Results

Reporting Surfaces

Administration

Documentation Index

​Endpoints

​List all results (paginated)

​Get a single result

​Get all results (sync)

​Get all results (unfiltered)

​Response shape

​Common fields on data

​Type-specific summaries

​knowledge_product → data.knowledge_product_summary

​innovation_development → data.innovation_development_summary

​innovation_use → data.innovation_use_summary

​capacity_sharing → data.capacity_development_summary

​policy_change → data.policy_change_summary

​innovation_package → data.ipsr_pathway_summary

​Payload conventions

​Reference JSON fragment

​Change log

Build docs developers (and LLMs) love

Endpoints

List all results (paginated)

Get a single result

Get all results (sync)

Get all results (unfiltered)

Response shape

Common fields on `data`

Type-specific summaries

`knowledge_product` → `data.knowledge_product_summary`

`innovation_development` → `data.innovation_development_summary`

`innovation_use` → `data.innovation_use_summary`

`capacity_sharing` → `data.capacity_development_summary`

`policy_change` → `data.policy_change_summary`

`innovation_package` → `data.ipsr_pathway_summary`

Payload conventions

Reference JSON fragment

Change log