Partner institution endpoints in the MARLO REST API

MARLO’s institution data is sourced from CLARISA (the CGIAR Reference Platform for Institutional Data), the authoritative registry of research organisations across the CGIAR system. The institutions API lets you browse the full institution catalogue, look up individual records, and submit requests for new institutions or country office additions — all of which flow through CLARISA’s approval workflow. All endpoints require a valid QA token. See Authentication for details.

Institution data reflects the CLARISA registry. New institutions and country office requests submitted via these endpoints enter a review queue. They do not appear as active institutions until a MARLO administrator accepts the request.

List all institutions

Retrieve the complete list of institutions available in MARLO (sourced from CLARISA).

GET /api/v2/controllist/institutions

This endpoint is not entity-scoped. Requires FULL_READ_REST_API_PERMISSION.

Response

Returns a JSON array of InstitutionDTO objects.

code

number

CLARISA-assigned institution code (used as the institution identifier across the API).

name

string

Full name of the institution.

acronym

string

Institution acronym (may be null).

websiteLink

string

Institution website URL.

added

string

Date the institution was added to the registry.

institutionType

object

Show InstitutionTypeDTO fields

number

Type identifier.

name

string

Type name (e.g., “CGIAR Research Center”, “University”).

countryOfficeDTO

object[]

List of country offices for this institution. Each object contains country information.

Example:

curl --request GET \
  --url 'https://your-marlo-host/api/v2/controllist/institutions' \
  --header 'Authorization: Bearer <your-token>'

Get an institution by ID

Retrieve a single institution by its CLARISA code.

GET /api/v2/controllist/institutions/{code}

This endpoint is not entity-scoped. Requires FULL_READ_REST_API_PERMISSION.

Path parameters

code

number

required

CLARISA institution code.

Example:

curl --request GET \
  --url 'https://your-marlo-host/api/v2/controllist/institutions/122' \
  --header 'Authorization: Bearer <your-token>'

Returns a single InstitutionDTO object. Returns 404 if not found.

List all institution types

Retrieve all institution type categories.

GET /api/v2/controllist/institution-types

This endpoint is not entity-scoped. Requires FULL_READ_REST_API_PERMISSION.

Response

Returns a JSON array of InstitutionTypeDTO objects.

number

Institution type identifier.

name

string

Institution type name (e.g., “University”, “Government”, “NGO”).

Example:

curl --request GET \
  --url 'https://your-marlo-host/api/v2/controllist/institution-types' \
  --header 'Authorization: Bearer <your-token>'

Get an institution type by ID

GET /api/v2/controllist/institution-types/{code}

Path parameters

code

number

required

Institution type identifier.

Returns a single InstitutionTypeDTO. Returns 404 if not found.

Submit a new institution request

Submit a request to add a new institution to the CLARISA registry. The request enters a review queue and must be approved by a MARLO administrator.

POST /api/v2/controllist/{CGIAREntity}/institutions/institution-requests

Requires FULL_CREATE_REST_API_PERMISSION.

Path parameters

CGIAREntity

string

required

CGIAR entity acronym on whose behalf the request is made.

Request body (`NewInstitutionDTO`)

name

string

required

Full name of the institution.

acronym

string

Institution acronym.

websiteLink

string

Institution website URL.

institutionTypeCode

string

required

The institution type code string. Use GET /institution-types to look up valid codes.

hqCountryIso

string

required

ISO Alpha-2 country code for the institution’s headquarters (e.g., "KE" for Kenya).

externalUserMail

string

required

Email address of the person submitting the request.

externalUserName

string

Name of the person submitting the request.

externalUserComments

string

Additional comments from the requester.

Example:

curl --request POST \
  --url 'https://your-marlo-host/api/v2/controllist/CCAFS/institutions/institution-requests' \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "East African Farmers Federation",
    "acronym": "EAFF",
    "websiteLink": "https://eaffu.org",
    "institutionTypeCode": "501",
    "hqCountryIso": "KE",
    "externalUserMail": "partner@example.org",
    "externalUserName": "Jane Smith",
    "externalUserComments": "Requested for CCAFS partnership project."
  }'

Returns an InstitutionRequestDTO with the request status.

List institution requests for a CGIAR entity

Retrieve all pending institution requests submitted under a CGIAR entity.

GET /api/v2/controllist/{CGIAREntity}/institutions/institution-all-requests

Requires FULL_READ_REST_API_PERMISSION.

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

Returns a JSON array of InstitutionRequestDTO objects.

number

Internal request ID.

partnerName

string

Name of the requested institution.

acronym

string

Acronym of the requested institution.

webPage

string

Website of the requested institution.

requestStatus

string

Current status of the request (e.g., Pending, Accepted, Rejected).

requestJustification

string

Rejection justification (populated when rejected).

countryDTO

object

Headquarter country information.

institutionTypeDTO

object

Institution type information.

institutionDTO

object

Populated after acceptance — the resulting InstitutionDTO record in CLARISA.

externalUserMail

string

Email of the requester.

externalUserName

string

Name of the requester.

externalUserComments

string

Comments from the requester.

Get a specific institution request by ID

GET /api/v2/controllist/{CGIAREntity}/institutions/institution-requests/{requestId}

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

requestId

number

required

Institution request ID.

Returns a single InstitutionRequestDTO. Returns 404 if not found.

Accept or reject an institution request

Approve or reject a pending institution request. This action is typically performed by a MARLO administrator.

POST /api/v2/controllist/{CGIAREntity}/institutions/accept-institution-request/{code}

Requires FULL_CREATE_REST_API_PERMISSION.

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

code

number

required

Institution request ID.

Query parameters

boolean

required

true to accept the request; false to reject it.

justification

string

Required when rejecting (accept=false). Reason for rejection.

Example — accept:

curl --request POST \
  --url 'https://your-marlo-host/api/v2/controllist/CCAFS/institutions/accept-institution-request/77?accept=true' \
  --header 'Authorization: Bearer <your-token>'

Example — reject:

curl --request POST \
  --url 'https://your-marlo-host/api/v2/controllist/CCAFS/institutions/accept-institution-request/77?accept=false&justification=Duplicate+of+existing+institution+code+122' \
  --header 'Authorization: Bearer <your-token>'

Returns an InstitutionRequestDTO with the updated requestStatus. Returns 404 if the request ID is not found.

Submit a country office request

Request the addition of a new country office location for an existing institution.

POST /api/v2/controllist/{CGIAREntity}/institutions/country-office-requests

Requires FULL_CREATE_REST_API_PERMISSION.

Request body (`NewCountryOfficeRequestDTO`)

institutionCode

number

required

CLARISA code of the institution to which the office should be added.

countryIso

string

required

ISO Alpha-2 country code for the new office location.

externalUserMail

string

required

Email of the person submitting the request.

externalUserName

string

Name of the person submitting the request.

externalUserComments

string

Additional comments.

Example:

curl --request POST \
  --url 'https://your-marlo-host/api/v2/controllist/CCAFS/institutions/country-office-requests' \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "institutionCode": 122,
    "countryIso": "ET",
    "externalUserMail": "partner@example.org",
    "externalUserName": "Jane Smith"
  }'

Returns a CountryOfficeRequestDTO with the new request details.

Get a country office request by ID

GET /api/v2/controllist/{CGIAREntity}/institutions/country-office-requests/{requestId}

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

requestId

number

required

Country office request ID.

Returns a CountryOfficeRequestDTO. Returns 404 if not found.

Common error codes

HTTP status	Meaning
`200`	Success
`404`	Institution, type, or request not found
`401`	Missing or expired token
`403`	Token valid but insufficient permissions
`400`	Request body validation failed (e.g., missing required `name`, invalid email format)

Setup & Build

Architecture Patterns

API Reference

Partner institution endpoints in the MARLO REST API

List all institutions

Response

Get an institution by ID

Path parameters

List all institution types

Response

Get an institution type by ID

Path parameters

Submit a new institution request

Path parameters

Request body (`NewInstitutionDTO`)

List institution requests for a CGIAR entity

Path parameters

Get a specific institution request by ID

Path parameters

Accept or reject an institution request

Path parameters

Query parameters

Submit a country office request

Request body (`NewCountryOfficeRequestDTO`)

Get a country office request by ID

Path parameters

Common error codes

Build docs developers (and LLMs) love

Setup & Build

Architecture Patterns

API Reference

Documentation Index

​List all institutions

​Response

​Get an institution by ID

​Path parameters

​List all institution types

​Response

​Get an institution type by ID

​Path parameters

​Submit a new institution request

​Path parameters

​Request body (NewInstitutionDTO)

​List institution requests for a CGIAR entity

​Path parameters

​Get a specific institution request by ID

​Path parameters

​Accept or reject an institution request

​Path parameters

​Query parameters

​Submit a country office request

​Request body (NewCountryOfficeRequestDTO)

​Get a country office request by ID

​Path parameters

​Common error codes

Build docs developers (and LLMs) love

List all institutions

Response

Get an institution by ID

Path parameters

List all institution types

Response

Get an institution type by ID

Path parameters

Submit a new institution request

Path parameters

Request body (`NewInstitutionDTO`)

List institution requests for a CGIAR entity

Path parameters

Get a specific institution request by ID

Path parameters

Accept or reject an institution request

Path parameters

Query parameters

Submit a country office request

Request body (`NewCountryOfficeRequestDTO`)

Get a country office request by ID

Path parameters

Common error codes