Results API — create, list, and manage PRMS results - PRMS — Planning, Reporting & Management System

The Results API is the core reporting surface of PRMS. Every piece of evidence that an initiative reports—policy changes, innovations, capacity sharing outcomes, and more—is modelled as a result. The endpoints below let you create result headers, fill in general information, manage geographic scope and partner associations, and retrieve filtered lists for reporting. All endpoints require the custom auth: <JWT> header returned by the authentication flow. The token is automatically refreshed on each successful request.

Authentication

All Results API endpoints enforce JWT authentication via the auth header. There is no public access. Requests without a valid token receive 401 Unauthorized with shouldRedirectToLogin: true. Expired tokens receive 401 with shouldRefreshToken: true.

auth: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Result types

The result_type_id field on every result record maps to one of the following values:

ID	Type
1	Policy Change
2	Innovation Use
3	Capacity Change
4	Other Outcome
5	Capacity Sharing for Development
6	Knowledge Product
7	Innovation Development
8	Other Output
9	Impact Contribution
10	Innovation Use (IPSR)
11	Complementary Innovation

Result statuses

ID	Name	Description
1	Editing	Result is being authored; not yet submitted for QA.
2	Quality Assessed	A QA reviewer has assessed the result positively.
3	Submitted	Result submitted to the reporting cycle.
4	Discontinued	Result has been discontinued.
5	Pending Review	Result is awaiting bilateral review.
6	Approved	Bilateral result has been approved by a reviewer.
7	Rejected	Bilateral result has been rejected; returned for revision.

Response envelope

Successful responses are wrapped by the ResponseInterceptor:

{
  "response": { ... },
  "message": "Successful response",
  "status": 200
}

Error responses from the global HttpExceptionFilter follow:

{
  "response": "...",
  "statusCode": 400,
  "message": "...",
  "timestamp": "2024-03-15T12:00:00.000Z",
  "path": "/api/results/..."
}

Core result endpoints

Create result header

Registers the base record for a new result and links it to the authenticated user. The returned id is used for all subsequent sub-resource writes.

POST /api/results/create/header

Request body

initiative_id

number

required

CLARISA initiative identifier that owns this result.

result_type_id

number

required

Result type (1–11). See the type table above.

result_level_id

number

required

Result level identifier (output, outcome, etc.).

result_name

string

required

Human-readable title for the result. Must be unique among active results.

handler

string

required

Short slug-style handle used to reference the result internally.

Example

curl -X POST https://prms.example.org/api/results/create/header \
  -H "auth: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "initiative_id": 50,
    "result_type_id": 1,
    "result_level_id": 2,
    "result_name": "National seed policy revised to include climate-resilient varieties",
    "handler": "seed-policy-2024"
  }'

Response fields

number

Internal primary key (bigint). Use this as resultId in sub-resource endpoints.

result_code

number

Auto-assigned sequential result code shown in the UI (e.g. 1042).

title

string

Confirmed title stored on the record.

result_type_id

number

Result type id as supplied.

status_id

number

Defaults to 1 (Editing) on creation.

version_id

number

Phase/version this result belongs to.

is_active

boolean

true on creation.

created_by

number

User id of the authenticated creator.

created_date

string

ISO-8601 timestamp of creation.

Get result by ID

Returns full result data for the provided internal identifier.

GET /api/results/get/:id

number

required

Internal result id (not result_code).

List all results (full)

Returns the complete list of registered results. Large datasets — prefer the filtered endpoint for production use.

GET /api/results/get/all/data

List simplified results

Returns a lightweight payload suitable for dropdowns and autocomplete widgets.

GET /api/results/get/all/simplified

Search results by name

Performs a partial-match search on the result title.

GET /api/results/get/name/:name

name

string

required

Search term matched against the result title.

Deep search by title

Runs the legacy deep-search pipeline, which searches across additional indexed fields.

GET /api/results/get/depth-search/:title

title

string

required

Search term passed to the full-text pipeline.

List results by user role (filtered)

The primary endpoint for the PRMS result list page. Returns paginated, filterable results associated with a given user. All query parameters are optional and can be comma-separated for multi-value filtering.

GET /api/results/get/all/roles/filter/:userId

userId

number

required

The user whose role memberships determine the visible result set.

initiative

string

Filter by initiative id or official code. Alias for submitter_id.

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 (1–11). Accepts comma-separated values.

status_id

string

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

portfolio_id

string

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

funding_source

string

Filter by funding source. Use W1/W2 for pool funding / Science Program results, or W3/Bilaterals for bilateral project results.

title

string

Full-text search term against the result title.

page

number

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

limit

number

Items per page. Only effective when page is also provided.

filter_created_by_me

boolean

When true, restricts to results where created_by matches the authenticated user.

filter_submitted_by_me

boolean

When true, restricts to results that have an active submission row for the authenticated user. When both filter_created_by_me and filter_submitted_by_me are true, rows matching either condition are included (OR logic).

Example

curl "https://prms.example.org/api/results/get/all/roles/filter/42?\
phase=34&result_type_id=1,7&status_id=1&page=1&limit=25" \
  -H "auth: $TOKEN"

Response fields

response

array

Array of result summary objects.

Show Result summary fields

number

Internal result id.

result_code

number

Human-facing result code.

title

string

Result title.

result_type_id

number

Result type (1–11).

status_id

number

Current status (1–7).

version_id

number

Reporting phase id.

reported_year_id

number

Reporting year (e.g. 2024).

is_active

boolean

Whether the result is active.

created_date

string

ISO-8601 creation timestamp.

last_updated_date

string

ISO-8601 last-update timestamp.

lead_initiative

object

Short object with the lead initiative id and official_code.

Soft delete a result

Marks a result as deleted (is_active = false). The record is preserved for audit purposes.

PATCH /api/results/delete/:id

number

required

Internal result id to delete.

justification

string

Optional operational justification stored on the deletion audit record.

Get science program progress

Aggregates reported results by Science Program (portfolio 3) and splits them by the authenticated user’s permissions.

GET /api/results/get/science-programs/progress

versionId

number

Optional phase/version identifier to scope the aggregation.

Get results by program and centers

Returns results grouped by project, filtered by program and optionally by center.

GET /api/results/by-program-and-centers

programId

string

required

Program identifier (e.g. SP01).

centerIds

string

One or more center ids, comma-separated (e.g. CT01,CT02).

Get pending review count

Returns the count of results pending review for a specific Science Program.

GET /api/results/pending-review

programId

string

required

Program identifier (e.g. SP01).

General information

Update general information

Creates or updates the full general information section of a result. Call this after creating the result header to supply the description, cross-cutting tags, partners, and KRS metadata.

PATCH /api/results/create/general-information

result_id

number

required

Internal result id to update.

result_name

string

required

Official result title.

result_description

string

required

Narrative description of the result.

result_type_id

number

required

Result type (1–11).

result_level_id

number

required

Result level identifier.

gender_tag_id

number

required

Gender tag level id.

climate_change_tag_id

number

Climate change tag level id.

nutrition_tag_level_id

number

Nutrition tag level id.

environmental_biodiversity_tag_level_id

number

required

Environmental / biodiversity tag level id.

poverty_tag_level_id

number

required

Poverty tag level id.

institutions

array

Array of { institutions_id: number } objects for partner institutions.

institutions_type

array

Array of { institutions_type_id: number } for institution types without a specific institution.

lead_contact_person

string

required

Full name of the lead contact person.

is_krs

boolean

required

Whether this result is registered in KRS.

krs_url

string

URL to the result’s KRS entry (required when is_krs is true).

is_discontinued

boolean

required

Whether the result has been discontinued.

Get general information

Retrieves the general information section for a result.

GET /api/results/get/general-information/result/:id

number

required

Internal result id.

Geographic scope

Save geographic scope

Sets the geographic scope for a result, including regions and countries.

PATCH /api/results/update/geographic/:resiltId

resiltId

number

required

Internal result id (note: the path param is intentionally spelled resiltId in the API).

geo_scope_id

number

required

CLARISA geographic scope identifier (global, regional, national, sub-national, etc.).

regions

array

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

countries

array

Array of { id: number, name: string } country objects when scope includes countries.

Get geographic scope

GET /api/results/get/geographic/:resiltId

resiltId

number

required

Internal result id.

Sub-resource endpoints

The following sub-resources are mounted as children of /api/results/. Each manages a specific aspect of the result record.

Evidences — /api/results/evidences/*

Manages supporting evidence links and documents attached to a result.

Method	Path	Description
GET	`/api/results/evidences/get/:resultId`	Retrieve all evidences for a result.
PATCH	`/api/results/evidences/save/:resultId`	Save (create or update) evidences for a result.

Evidence records carry a link (URL), description, and evidence_type_id classifying the document.

Geographic scope (countries/regions) — /api/results/result-countries/* and /api/results/result-regions/*

Fine-grained country and region associations, distinct from the top-level geographic scope field.

Method	Path	Description
GET	`/api/results/result-countries/get/:resultId`	List countries linked to a result.
PATCH	`/api/results/result-countries/save/:resultId`	Save country associations.
GET	`/api/results/subnational/get/:resultId`	List sub-national scope records.
PATCH	`/api/results/subnational/save/:resultId`	Save sub-national scope.

Partners and institutions — /api/results/results-by-institutions/*

Manages partner/institution links for a result, including delivery type and role.

Method	Path	Description
GET	`/api/results/results-by-institutions/get/:resultId`	List all partner institutions for a result.
PATCH	`/api/results/results-by-institutions/save/:resultId`	Save partner institution associations.

Each institution record includes institution_id, institution_roles_id, and optionally delivery-type sub-records.

ToC links — /api/results/toc/*

Manages Theory of Change (ToC) alignments — linking a result to ToC nodes from one or more initiatives.

Method	Path	Description
GET	`/api/results/toc/get/:resultId`	Retrieve ToC result links for a result.
PATCH	`/api/results/toc/save/:resultId`	Save ToC result links.

Each ToC link record references a toc_result_id (from the /toc/ API) and carries contributing initiative information.

Actors — /api/results/actors/*

Records the people and target groups directly associated with a result (e.g. farmers reached, researchers trained).

Method	Path	Description
GET	`/api/results/actors/get/:resultId`	List actor records for a result.
PATCH	`/api/results/actors/save/:resultId`	Save actor records.

Actor records include actor_type_id, sex_and_age_disaggregation, how_many, and optional age-range breakdowns.

Budget — /api/results/result-budget (non-pooled projects)

Manages W3/bilateral budget links associated with a result via non-pooled projects.

Method	Path	Description
GET	`/api/results/non-pooled-projects/get/:resultId`	List non-pooled project budget records.
PATCH	`/api/results/non-pooled-projects/save/:resultId`	Save non-pooled project budget links.

Each record carries grant_title, center_grant_id, funder_institution_id, and lead_center_id.

Submissions — /api/results/submissions/*

Controls the submission lifecycle of a result.

Method	Path	Description
PATCH	`/api/results/submissions/submit/:resultId`	Submit a result (moves toward status `Submitted`).
PATCH	`/api/results/submissions/unsubmit/:resultId`	Retract a submission and return to `Editing`.
PATCH	`/api/results/submissions/submit-ipsr/:resultId`	Submit an IPSR innovation package.
PATCH	`/api/results/submissions/unsubmit-ipsr/:resultId`	Retract an IPSR submission.

Linked results — /api/results/linked/*

Links one result to related results across the platform.

Method	Path	Description
GET	`/api/results/linked/get/:resultId`	Retrieve linked result records.
PATCH	`/api/results/linked/save/:resultId`	Save linked result associations.

Impact areas — /api/results/impact-area-indicators/* and /api/results/impact-area-target/*

Records alignment of a result with CGIAR impact areas (food security, poverty, nutrition, etc.).

Method	Path	Description
GET	`/api/results/impact-area-indicators/get/:resultId`	List impact area indicator alignments.
PATCH	`/api/results/impact-area-indicators/save/:resultId`	Save impact area indicator alignments.
GET	`/api/results/impact-area-target/get/:resultId`	List impact area targets.
PATCH	`/api/results/impact-area-target/save/:resultId`	Save impact area targets.

Reporting exports

Basic reporting list

Returns the dataset used to generate the basic Excel report. All filters are optional.

POST /api/results/get/reporting/list

Request body

initDate

string

Filter results created on or after this date (YYYY-MM-DD).

endDate

string

Filter results created on or before this date (YYYY-MM-DD). Must be ≥ initDate when both are provided.

phases

array

Array of { id: number } phase objects to filter by.

searchText

string

Full-text search applied to result title and result code.

inits

array

Array of { id: number } or { official_code: string } initiative filter objects.

indicatorCategories

array

Array of { id: number } result type filter objects.

status

array

Array of { status_id: number } status filter objects.

fundingSource

array

Array of { name: string } with values "W1/W2" or "W3/Bilaterals".

filterCreatedByMe

boolean

When true, only returns results created by the authenticated user.

filterSubmittedByMe

boolean

When true, only returns results submitted by the authenticated user. Combined with filterCreatedByMe as OR logic when both are true.

Example

curl -X POST https://prms.example.org/api/results/get/reporting/list \
  -H "auth: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phases": [{ "id": 34 }],
    "indicatorCategories": [{ "id": 1 }, { "id": 7 }],
    "status": [{ "status_id": 3 }]
  }'

Full-metadata export (async)

Queues an asynchronous job that builds a multi-sheet Excel workbook. When complete, the authenticated user receives an email with a time-limited S3 download link.

POST /api/results/get/reporting/full-metadata-export/jobs

Accepts the same filter body as the basic reporting list. Returns 202 Accepted with a jobId. Response

{
  "response": { "jobId": "abc123-def456" },
  "message": "Export queued",
  "status": 202
}

Get export job status

GET /api/results/get/reporting/full-metadata-export/jobs/:jobId

jobId

string

required

Job id returned by the queue endpoint.

response.status

string

Job status: pending, processing, done, or failed.

response.downloadUrl

string

Time-limited S3 pre-signed URL. Present only when status is done.

Bilateral result endpoints

Results sourced from bilateral projects (source = "API") have additional endpoints for review workflows.

GET /api/results/bilateral/:resultId — Get bilateral result

Returns the complete bilateral result record including all type-specific summary fields.

resultId

number

required

Internal result id.

PATCH /api/results/bilateral/review-update/data-standard/:resultId — Update data standard fields

Updates ToC fields and Minimum Data Standard fields of a bilateral result in PENDING_REVIEW status.

updateExplanation

string

required

Explanation required for any field modification.

PATCH /api/results/bilateral/:resultId/review-decision — Approve or reject

Processes a review decision (approve or reject) for a bilateral result in PENDING_REVIEW status.

decision

string

required

"APPROVED" or "REJECTED".

justification

string

Required when decision is "REJECTED".

PATCH /api/results/bilateral/:resultId/title — Update title

Updates the title of a bilateral result. The result must be in EDITING status unless the user has Admin privileges. The new title must be unique among active results.

title

string

required

New result title. Must be unique.

Reference endpoints

Institutions

Method	Path	Description
GET	`/api/results/get/institutions/all`	List all institutions linked to results.
GET	`/api/results/get/institutions-type/all`	List all institution types.
GET	`/api/results/get/institutions-type/new`	List institution types available for new records.
GET	`/api/results/get/institutions-type/childless`	List institution types with no child relationships.
GET	`/api/results/get/institutions-type/legacy`	List legacy institution types.

Result types and levels

Method	Path	Description
GET	`/api/results/types`	List all result types.
GET	`/api/results/levels`	List all result levels.
GET	`/api/results/type-by-level`	List result types scoped to their valid levels.

Centers, versions, and years

Method	Path	Description
GET	`/api/results/get/centers/:resultId`	List centers associated with a result.
GET	`/api/results/versions`	List reporting phases/versions.
GET	`/api/results/years`	List available reporting years.

Overview

Results

Reporting Surfaces

Administration

Results API — create, list, and manage PRMS results

Authentication

Result types

Result statuses

Response envelope

Core result endpoints

Create result header

Get result by ID

List all results (full)

List simplified results

Search results by name

Deep search by title

List results by user role (filtered)

Soft delete a result

Get science program progress

Get results by program and centers

Get pending review count

General information

Update general information

Get general information

Geographic scope

Save geographic scope

Get geographic scope

Sub-resource endpoints

Reporting exports

Basic reporting list

Full-metadata export (async)

Get export job status

Bilateral result endpoints

Reference endpoints

Build docs developers (and LLMs) love

Overview

Results

Reporting Surfaces

Administration

Documentation Index

​Authentication

​Result types

​Result statuses

​Response envelope

​Core result endpoints

​Create result header

​Get result by ID

​List all results (full)

​List simplified results

​Search results by name

​Deep search by title

​List results by user role (filtered)

​Soft delete a result

​Get science program progress

​Get results by program and centers

​Get pending review count

​General information

​Update general information

​Get general information

​Geographic scope

​Save geographic scope

​Get geographic scope

​Sub-resource endpoints

​Reporting exports

​Basic reporting list

​Full-metadata export (async)

​Get export job status

​Bilateral result endpoints

​Reference endpoints

Build docs developers (and LLMs) love

Authentication

Result types

Result statuses

Response envelope

Core result endpoints

Create result header

Get result by ID

List all results (full)

List simplified results

Search results by name

Deep search by title

List results by user role (filtered)

Soft delete a result

Get science program progress

Get results by program and centers

Get pending review count

General information

Update general information

Get general information

Geographic scope

Save geographic scope

Get geographic scope

Sub-resource endpoints

Reporting exports

Basic reporting list

Full-metadata export (async)

Get export job status

Bilateral result endpoints

Reference endpoints