API V2#

For: developers

The official OpenSPP REST API (V2) provides a modern, secure, and standards-compliant interface for integrating with OpenSPP. Built on FastAPI, it replaces the legacy XML-RPC API with OAuth 2.0 authentication, consent-based access control, external identifier references, and RFC 9457 error responses.

How to use this section#

  1. Read API V2 Overview for the design philosophy and core concepts

  2. Read the reference pages for the features you need:

  3. Follow the Tutorial: build a Python API client to tie everything together in a working Python client

  4. Consult Studio API Integration and the extension APIs as you need them

Prerequisites#

  • Familiarity with REST APIs and HTTP

  • Ability to issue HTTP requests from your integration environment (Python, JavaScript, curl, etc.)

  • An OpenSPP deployment with spp_api_v2 installed

  • An API client registered in OpenSPP with the scopes you need (see Authentication)

When do you need API V2?#

The API is the primary integration surface between OpenSPP and external systems. Use it when you need to:

Requirement

API V2

Alternative

Read/write registrants from an external system

Yes

Trigger operations from a portal or mobile app

Yes

Bulk-import beneficiary data

Yes ($bulk, $batch)

Integrate with DCI-compliant systems

Yes

DCI client module

Automate change requests across systems

Yes

Extend OpenSPP with internal Python code

Custom modules

Add custom program logic

Custom program managers

Build no-code CR types

Change request types

Core topics#

Topic

Description

API V2 Overview

Design philosophy, base URL, core principles, FHIR-inspired patterns

Authentication

OAuth 2.0, JWT tokens, scopes, and rate limiting

External Identifiers

Namespaced external IDs instead of database IDs

Consent Management

Privacy-first consent mechanisms and field-level access

API Resources

Individual, Group, Program, and ProgramMembership resources

Search and Filtering

Query parameters, pagination, sorting, and advanced filters

Batch Operations

Transaction bundles, batch operations, and bulk export

Error Handling

Error responses (RFC 9457) and status codes

Tutorial: build a Python API client

Build a working Python API client end-to-end

Studio API Integration

Studio custom fields and CEL variables via API

Extension APIs#

These modules add domain-specific endpoints when installed alongside the core spp_api_v2 module:

Topic

Module

Description

Entitlements and Cycles

spp_api_v2_entitlements, spp_api_v2_cycles

Cash/in-kind entitlements and distribution cycles

Products and Service Points

spp_api_v2_products, spp_api_v2_service_points

Product catalog and distribution locations

Note

API V2 completely replaces the legacy XML-RPC API. New integrations should use API V2.

See also#