IPSR Innovation Package API endpoints — PRMS - PRMS — Planning, Reporting & Management System

The Innovation Package and Scaling Readiness (IPSR) module lets initiatives bundle innovation development results into structured innovation packages that are ready for wider deployment. An innovation package references one or more existing Innovation Development (result_type_id = 7) and Innovation Use (result_type_id = 2) results and layers on additional metadata: a four-step innovation pathway, complementary innovations, expert panel assessments, a package-level Theory of Change alignment, and geographic / partner coverage. All endpoints in this group require the auth: <JWT> header.

Authentication

All IPSR API endpoints enforce JWT authentication via the auth header. Requests without a valid token receive 401 Unauthorized. Role enforcement at the handler level uses @Roles guards where applicable.

auth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Mount structure

IPSR endpoints are split across two top-level paths:

Prefix	What it covers
`/api/ipsr/*`	Innovation package authoring: header creation, pathway steps 1–4, experts, assessments, ToC links.
`/api/ipsr-framework/*`	Cross-result IPSR framework reporting (aggregate views).

The sub-resource paths under /api/ipsr/ are:

Sub-path	Module
`/api/ipsr/results-innovation-package/*`	Core innovation package header record
`/api/ipsr/innovation-pathway/*`	Four-step innovation pathway
`/api/ipsr/innovation-packaging-experts/*`	Expert panel expertise reference data
`/api/ipsr/contributors/*`	Package→ToC result alignments
`/api/ipsr/assessed-during-expert-workshop/*`	Workshop assessment options
`/api/ipsr/results-innovation-packages-validation-module/*`	Package validation state
`/api/ipsr/results-innovation-packages-enabler-type/*`	Enabler type reference data

Core package endpoints (`/api/ipsr/*`)

List all innovations

Returns Innovation Development results available to link into a package. Optionally scoped to a list of initiative ids.

POST /api/ipsr/all-innovations

Request body

initiativeId

number[]

Array of initiative ids to restrict the innovation list. Omit or send an empty array to return all visible innovations.

Example

curl -X POST https://prms.example.org/api/ipsr/all-innovations \
  -H "auth: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "initiativeId": [12, 50] }'

Response fields

response

array

Array of Innovation Development result summaries.

Show Innovation fields

number

Internal result id.

result_code

number

Human-facing result code.

title

string

Result title.

result_type_id

number

Always 7 (Innovation Development) for this endpoint.

status_id

number

Current status (1–7).

version_id

number

Reporting phase id.

Get single innovation

Returns full data for a single Innovation Development result for preview before linking.

GET /api/ipsr/innovation/:resultId

resultId

number

required

Internal result id of the Innovation Development result.

List all innovation packages

Returns all innovation packages visible to the authenticated user.

GET /api/ipsr/all-innovation-packages

List innovation packages (filtered)

The primary package list endpoint. Returns paginated, filterable innovation packages.

GET /api/ipsr/all-innovation-packages/filter

initiative

string

Filter by initiative id or official code. Alias for submitter_id. Accepts comma-separated values.

phase

string

Reporting phase (version) id. Alias for version_id. Accepts comma-separated values.

version_id

string

Filter by phase/version id. Accepts comma-separated values.

result_type_id

string

Filter by result type id. Accepts comma-separated values.

portfolio_id

string

Filter by CLARISA portfolio id. Accepts comma-separated values.

status_id

string

Filter by result status id (1–7). Accepts comma-separated values.

page

number

Page number (1-based). When provided alongside limit, the response includes a meta pagination block.

limit

number

Items per page.

Example

curl "https://prms.example.org/api/ipsr/all-innovation-packages/filter?\
phase=34&status_id=1,2&page=1&limit=20" \
  -H "auth: $TOKEN"

Get innovation package detail

Returns the full detail view for an innovation package, including all linked results and step data.

GET /api/ipsr/innovation-package-detail/:resultId

resultId

number

required

Internal result id of the innovation package.

Get IPSR Excel report

Generates and returns the IPSR Excel report for a given set of packages.

POST /api/ipsr/get/excel-report

resultId

number

required

Internal result id of the innovation package to export.

Innovation package header (`/api/ipsr/results-innovation-package/*`)

The header record holds the top-level metadata of the package—title, description, geographic scope, and cross-cutting tags.

Create package header

POST /api/ipsr/results-innovation-package/create-header

result_id

number

required

The Innovation Development result id that seeds this package.

initiative_id

number

required

Owning initiative id.

geo_scope_id

number

required

CLARISA geographic scope identifier.

regions

array

Array of { id: number, name: string } region objects when the scope covers regions.

countries

array

Array of { id: number, name: string } country objects, each optionally with a sub_national array of sub-national scope records.

Response fields

response.id

number

Internal id of the newly created innovation package record.

response.result_id

number

The source Innovation Development result id.

Update general information

Updates title, description, cross-cutting tag levels, KRS registration, and discontinuation state for an existing package.

PATCH /api/ipsr/results-innovation-package/general-information/:resultId

resultId

number

required

Internal result id of the innovation package.

title

string

Package title.

description

string

Narrative description of the innovation package.

lead_contact_person

string

Full name of the lead contact person.

gender_tag_level_id

number

Gender tag level.

climate_change_tag_level_id

number

Climate change tag level.

nutrition_tag_level_id

number

Nutrition tag level.

environmental_biodiversity_tag_level_id

number

Environmental / biodiversity tag level.

poverty_tag_level_id

number

Poverty tag level.

is_krs

boolean

Whether the package is registered in KRS.

krs_url

string

KRS entry URL (required when is_krs is true).

is_discontinued

boolean

required

Whether the package has been discontinued.

Delete package

Soft-deletes an innovation package (is_active = false).

DELETE /api/ipsr/results-innovation-package/:resultId

resultId

number

required

Internal result id to delete.

justification

string

Optional justification stored on the deletion audit record.

Reference lookups

GET /api/ipsr/results-innovation-package/active-backstopping
GET /api/ipsr/results-innovation-package/consensus-initiative-work-package
GET /api/ipsr/results-innovation-package/regional-integrated
GET /api/ipsr/results-innovation-package/regional-leadership
GET /api/ipsr/results-innovation-package/relevant-country
GET /api/ipsr/results-innovation-package/unit-time

These endpoints return reference data used to populate dropdowns in the package general information form.

Innovation pathway (`/api/ipsr/innovation-pathway/*`)

The innovation pathway records the four-step journey from innovation development to scaled uptake. Each step is managed independently. All step endpoints require the result id of the parent innovation package.

Step 1 — Innovation readiness and use

Step 1 captures the core innovation package composition: which results are included and the readiness / use scores from the IPSR framework.Get Step 1

GET /api/ipsr/innovation-pathway/get-step-one/:resultId

Save Step 1

PATCH /api/ipsr/innovation-pathway/save/step-one/:resultId

resultId

number

required

Internal result id of the innovation package.

readiness_level

number

IPSR readiness level score (1–9).

use_level

number

IPSR use level score (1–9).

experts

array

Array of expert records with expertise and assessment scores.

Retrieve Action Area outcomesRetrieves Action Area outcome alignments for Step 1 from existing ToC data.

PATCH /api/ipsr/innovation-pathway/retrieve/aa-outcomes/:resultId

Step 2 — Complementary innovations

Step 2 links complementary innovations—existing PRMS results (types 2 or 7) that the package depends on.Get Step 2

GET /api/ipsr/innovation-pathway/get/step-two/:resultId

Save Step 2 (bulk update)

PATCH /api/ipsr/innovation-pathway/save/step-two/:resultId

complementaryInovatins

array

Array of complementary innovation link objects to save. Replaces existing associations.

Create a complementary innovationCreates a single new complementary innovation record linked to the package.

POST /api/ipsr/innovation-pathway/save/complementary-innovation/:resultId

result_id

number

required

The PRMS result id to link as a complementary innovation.

complementary_innovation_enabler_type_id

number

Enabler type classification for this complementary innovation.

Get complementary innovation by id

GET /api/ipsr/innovation-pathway/get/complementary-innovation/:complementaryInnovationId

Update a complementary innovation

PATCH /api/ipsr/innovation-pathway/updated/complementary-innovation/:complementaryInnovationId

Delete (inactivate) a complementary innovation

DELETE /api/ipsr/innovation-pathway/delete/complementary-innovation/:complementaryInnovationId

Reference data

GET /api/ipsr/innovation-pathway/get/complementary-innovations
GET /api/ipsr/innovation-pathway/get/complementary-innovations-functions

Step 3 — Expert workshop and assessment

Step 3 records the expert workshop details and the scaling assessment made during the workshop.Get Step 3

GET /api/ipsr/innovation-pathway/get/step-three/:resultId

Save Step 3

PATCH /api/ipsr/innovation-pathway/save/step-three/:resultId

resultId

number

required

Internal result id of the innovation package.

result_ip_expert_workshop_organized

object

Workshop metadata: date, location, number of participants.

assessed_during_expert_workshop

array

Array of assessment option ids selected during the workshop.

consensus_initiative_work_package_id

number

Consensus initiative work package reference.

Step 4 — Scaling ambition and budget

Step 4 captures scaling ambition, partner involvement, and budget linkage for the innovation package.Get Step 4

GET /api/ipsr/innovation-pathway/get/step-four/:resultId

Save Step 4 (main)

PATCH /api/ipsr/innovation-pathway/save/step-four/:resultId

active_backstopping_id

number

Backstopping support type identifier.

regional_leadership_id

number

Regional leadership scope identifier.

regional_integrated_id

number

Regional integration scope identifier.

relevant_country_id

number

Relevant country classification identifier.

Save Step 4 partners

PATCH /api/ipsr/innovation-pathway/save/step-four/partners/:resultId

institutions

array

Array of { institution_id: number, institution_roles_id: number } partner objects.

Save Step 4 bilateral links

PATCH /api/ipsr/innovation-pathway/save/step-four/bilaterals/:resultId

toc_id

number

ToC node identifier for bilateral alignment.

donors

array

Array of donor institution objects with contribution amounts.

Expert panel (`/api/ipsr/innovation-packaging-experts/*`)

List expertise options

Returns the catalogue of expertise areas used to classify expert panel members.

GET /api/ipsr/innovation-packaging-experts/expertises

Response fields

response

array

Array of expertise objects.

Show Expertise fields

number

Expertise id.

name

string

Expertise label shown in the UI.

is_active

boolean

Whether this expertise option is currently active.

Workshop assessment reference data (`/api/ipsr/assessed-during-expert-workshop/*`)

List assessment options

Returns all predefined assessment scenarios that can be selected to describe what was assessed during the expert workshop (Step 3).

GET /api/ipsr/assessed-during-expert-workshop

Response fields

response

array

Array of assessment option objects.

Show Assessment option fields

number

Assessment option id.

description

string

Human-readable description of the assessment scenario.

is_active

boolean

Whether this option is currently selectable.

Package→ToC alignment (`/api/ipsr/contributors/*`)

Manages the Theory of Change alignment for an innovation package — linking the package to ToC nodes and recording contributing initiative data.

Save ToC alignment

PATCH /api/ipsr/contributors/save/:resultId

resultId

number

required

Internal result id of the innovation package.

toc_result_id

number

required

The ToC result node id to align this package to.

initiative_id

number

Contributing initiative id.

contributing_np_projects

array

Non-pooled project contributions to this ToC alignment.

Get ToC alignment

GET /api/ipsr/contributors/get/:resultId

resultId

number

required

Internal result id of the innovation package.

Response fields

response

array

Array of ToC alignment records for the package.

Show ToC alignment fields

result_id

number

Innovation package result id.

toc_result_id

number

Linked ToC result node id.

initiative_id

number

Contributing initiative id.

is_active

boolean

Whether this alignment is active.

Enabler types reference data

Returns the list of enabler type classifications used to categorise complementary innovations.

GET /api/ipsr/results-innovation-packages-enabler-type

IPSR framework (`/api/ipsr-framework/*`)

The ipsr-framework module provides aggregate views across all innovation packages for framework-level reporting. It is mounted at a separate top-level path from the package authoring endpoints.

The /api/ipsr-framework/* endpoints are intended for cross-result IPSR framework reporting consumers (PMU, platform reports). These endpoints aggregate data across multiple packages and are not used for individual package authoring.

The available sub-routes are defined in ipsr-framework.routes.ts and cover aggregated geographic coverage, complementary innovation summaries, and initiative-level package tallies.

Submission lifecycle

IPSR innovation packages use the same submission service as standard results but via dedicated IPSR endpoints under /api/results/submissions/:

Method	Path	Description
PATCH	`/api/results/submissions/submit-ipsr/:resultId`	Submit an innovation package to the reporting cycle.
PATCH	`/api/results/submissions/unsubmit-ipsr/:resultId`	Retract an innovation package submission.

resultId

number

required

Internal result id of the innovation package.

Submission advances the package status_id toward Submitted (3) following QA approval. The package must pass validation before submission is accepted.

Key relationships

Innovation Package (result_type_id = 10 / INNOVATION_USE_IPSR)
├── links to Innovation Development result (result_type_id = 7)
├── links to Innovation Use results (result_type_id = 2)
├── has many Complementary Innovations (result_type_id = 11)
│   └── each classified by enabler_type
├── has many Expert Panel members
│   └── each classified by expertise area
├── Step 3: Expert Workshop assessment options
├── Package→ToC alignments (via /api/ipsr/contributors/)
├── Geographic coverage (countries, regions)
└── Budget links (non-pooled projects)

Overview

Results

Reporting Surfaces

Administration

IPSR Innovation Package API endpoints — PRMS

Authentication

Mount structure

Core package endpoints (`/api/ipsr/*`)

List all innovations

Get single innovation

List all innovation packages

List innovation packages (filtered)

Get innovation package detail

Get IPSR Excel report

Innovation package header (`/api/ipsr/results-innovation-package/*`)

Create package header

Update general information

Delete package

Reference lookups

Innovation pathway (`/api/ipsr/innovation-pathway/*`)

Expert panel (`/api/ipsr/innovation-packaging-experts/*`)

List expertise options

Workshop assessment reference data (`/api/ipsr/assessed-during-expert-workshop/*`)

List assessment options

Package→ToC alignment (`/api/ipsr/contributors/*`)

Save ToC alignment

Get ToC alignment

Enabler types reference data

IPSR framework (`/api/ipsr-framework/*`)

Submission lifecycle

Key relationships

Build docs developers (and LLMs) love

Overview

Results

Reporting Surfaces

Administration

Documentation Index

​Authentication

​Mount structure

​Core package endpoints (/api/ipsr/*)

​List all innovations

​Get single innovation

​List all innovation packages

​List innovation packages (filtered)

​Get innovation package detail

​Get IPSR Excel report

​Innovation package header (/api/ipsr/results-innovation-package/*)

​Create package header

​Update general information

​Delete package

​Reference lookups

​Innovation pathway (/api/ipsr/innovation-pathway/*)

​Expert panel (/api/ipsr/innovation-packaging-experts/*)

​List expertise options

​Workshop assessment reference data (/api/ipsr/assessed-during-expert-workshop/*)

​List assessment options

​Package→ToC alignment (/api/ipsr/contributors/*)

​Save ToC alignment

​Get ToC alignment

​Enabler types reference data

​IPSR framework (/api/ipsr-framework/*)

​Submission lifecycle

​Key relationships

Build docs developers (and LLMs) love

Authentication

Mount structure

Core package endpoints (`/api/ipsr/*`)

List all innovations

Get single innovation

List all innovation packages

List innovation packages (filtered)

Get innovation package detail

Get IPSR Excel report

Innovation package header (`/api/ipsr/results-innovation-package/*`)

Create package header

Update general information

Delete package

Reference lookups

Innovation pathway (`/api/ipsr/innovation-pathway/*`)

Expert panel (`/api/ipsr/innovation-packaging-experts/*`)

List expertise options

Workshop assessment reference data (`/api/ipsr/assessed-during-expert-workshop/*`)

List assessment options

Package→ToC alignment (`/api/ipsr/contributors/*`)

Save ToC alignment

Get ToC alignment

Enabler types reference data

IPSR framework (`/api/ipsr-framework/*`)

Submission lifecycle

Key relationships