openspp@4.0.0

addToGroup(groupId, individualId, [role], [options])

createGroup(data)

createIndividual(data)

enroll(beneficiary, programId, [options])

getEnrolledPrograms(beneficiary)

getGroup(id, [options])

getGroupMembers(groupId, [options])

getIndividual(id, [options])

getProgram(id)

getPrograms([options])

getServicePoint(name)

removeFromGroup(groupId, individualId, [options])

request(method, path, [body], [options])

searchGroup([query], [options])

searchIndividual([query], [options])

searchServicePoint([query], [options])

unenroll(beneficiary, programId, [options])

updateGroup(id, data, [options])

updateIndividual(id, data, [options])

This adaptor exports the following from common:

combine()

dataPath()

dataValue()

dateFns

each()

field()

fields()

fn()

fnIf()

lastReferenceValue()

log()

merge()

sourceValue()

Functions

addToGroup

addToGroup(groupId, individualId, [role], [options]) ⇒ Operation

Add an individual to a group. Throws a 409 error if the individual is already a member. To change an existing member's role, use request with both identifiers URL-encoded, eg request("PATCH", "/Group/<group>/member/<individual>", { role: { coding: [{ system: "urn:openspp:vocab:group-membership-type", code: "spouse" }] } }).

Param	Type	Description
groupId	string	Group identifier as system|value
individualId	string	Individual identifier as system|value
[role]	string | object	Role code in urn:openspp:vocab:group-membership-type (eg "head", "spouse", "child"), or a CodeableConcept
[options]	object	startDate (YYYY-MM-DD)

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example: Add as head of household

addToGroup("urn:openspp:vocab:id-type#household_id|HH-1", "urn:openspp:vocab:id-type#national_id|PH-123", "head");

Example: Add without a role

addToGroup("urn:openspp:vocab:id-type#household_id|HH-1", "urn:openspp:vocab:id-type#national_id|PH-123");

---

createGroup

createGroup(data) ⇒ Operation

Create a group.

Param	Type	Description
data	object	Group resource, with at least one identifier. See the OpenSPP resource docs

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

createGroup({
  identifier: [{ system: "urn:openspp:vocab:id-type#household_id", value: "HH-1" }],
  name: "Santos Household",
  groupType: "household",
});

---

createIndividual

createIndividual(data) ⇒ Operation

Create an individual.

Param	Type	Description
data	object	Individual resource, with at least one identifier. See the OpenSPP resource docs

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

createIndividual({
  identifier: [{ system: "urn:openspp:vocab:id-type#national_id", value: "PH-123456789" }],
  name: { family: "Santos", given: "Maria" },
  birthDate: "1985-03-15",
  gender: { coding: [{ system: "urn:iso:std:iso:5218", code: "2" }] },
});

---

enroll

enroll(beneficiary, programId, [options]) ⇒ Operation

Enroll a registrant in a program. If they are already enrolled, returns their membership unchanged. If they have a membership in this program that isn't enrolled (eg exited), it is set back to enrolled. That update throws if the registrant also has memberships in other programs, because the adaptor can't be sure OpenSPP would update the membership for this program.

Param	Type	Description
beneficiary	string	Typed reference: Individual/system|value or Group/system|value
programId	string	Program identifier as system|value
[options]	object	enrollmentDate (YYYY-MM-DD) for new memberships

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

enroll("Individual/urn:openspp:vocab:id-type#national_id|PH-123", "urn:openspp:program|universal-child-grant");

---

getEnrolledPrograms

getEnrolledPrograms(beneficiary) ⇒ Operation

List the programs a registrant is enrolled in, as ProgramMembership resources (each has a program reference).

Param	Type	Description
beneficiary	string	Typed reference: Individual/system|value or Group/system|value

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

getEnrolledPrograms("Group/urn:openspp:vocab:id-type#household_id|HH-1");

---

getGroup

getGroup(id, [options]) ⇒ Operation

Get a group by identifier. To read the members, use getGroupMembers.

Param	Type	Description
id	string	Identifier as system|value
[options]	object	elements and extensions (see SearchOptions)

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

getGroup("urn:openspp:vocab:id-type#household_id|HH-1");

---

getGroupMembers

getGroupMembers(groupId, [options]) ⇒ Operation

List the individuals who are members of a group.

Param	Type	Description
groupId	string	Group identifier as system|value
[options]	object	role (membership role code) plus SearchOptions

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

getGroupMembers("urn:openspp:vocab:id-type#household_id|HH-1");

Example: Only the head of household

getGroupMembers("urn:openspp:vocab:id-type#household_id|HH-1", { role: "head" });

---

getIndividual

getIndividual(id, [options]) ⇒ Operation

Get an individual by identifier.

Param	Type	Description
id	string	Identifier as system|value
[options]	object	elements and extensions (see SearchOptions)

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

getIndividual("urn:openspp:vocab:id-type#national_id|PH-123456789");

Example: Only return some fields

getIndividual("urn:openspp:vocab:id-type#national_id|PH-123456789", { elements: ["identifier", "name"] });

---

getProgram

getProgram(id) ⇒ Operation

Get a program by identifier.

Param	Type	Description
id	string	Program identifier as system|value

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

getProgram("urn:openspp:program|universal-child-grant");

---

getPrograms

getPrograms([options]) ⇒ Operation

List programs.

Param	Type	Description
[options]	ProgramOptions	Filters and paging

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

getPrograms();

Example: Programs for groups, 10 per page

getPrograms({ targetType: "group", count: 10 });

---

getServicePoint

getServicePoint(name) ⇒ Operation

Get a service point by its identifier (the service point name).

Param	Type	Description
name	string	Service point identifier (its name)

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

getServicePoint("Agoncillo Payment Center");

---

removeFromGroup

removeFromGroup(groupId, individualId, [options]) ⇒ Operation

End an individual's membership of a group. OpenSPP sets the end date to now unless endedDate is given.

Param	Type	Description
groupId	string	Group identifier as system|value
individualId	string	Individual identifier as system|value
[options]	object	reason (OpenSPP logs it but doesn't save it), endedDate (YYYY-MM-DD)

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

removeFromGroup("urn:openspp:vocab:id-type#household_id|HH-1", "urn:openspp:vocab:id-type#national_id|PH-123", { reason: "Moved out" });

---

request

request(method, path, [body], [options]) ⇒ Operation

Make a request to any OpenSPP REST API v2 endpoint. Paths are relative to /api/v2/spp.

Param	Type	Description
method	string	HTTP method
path	string	Path relative to /api/v2/spp, eg /Individual
[body]	object	Request body, sent as JSON
[options]	object	query (query parameters), ifMatch (ETag for optimistic locking) and headers

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example: List vocabularies

request("GET", "/Vocabulary", null, { query: { _count: 10 } });

Example: Read GIS layers

request("GET", "/gis/ogc/collections");

---

searchGroup

searchGroup([query], [options]) ⇒ Operation

Search groups.

Param	Type	Description
[query]	object	OpenSPP search parameters, eg { name: "Santos" }. See the OpenSPP search docs
[options]	SearchOptions	Paging and field options

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

searchGroup({ name: "Santos" }, { count: 50 });

---

searchIndividual

searchIndividual([query], [options]) ⇒ Operation

Search individuals. Records the API client may not see (eg without consent) are left out.

Param	Type	Description
[query]	object	OpenSPP search parameters, eg { name: "Santos" }. identifier and group must be system|value. See the OpenSPP search docs
[options]	SearchOptions	Paging and field options

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example: Search by name

searchIndividual({ name: "Santos" });

Example: Born on or after 2010, 50 per page, second page

searchIndividual({ birthdate: "ge2010-01-01" }, { count: 50, offset: 50 });

Example: Heads of household in a group

searchIndividual({ group: "urn:openspp:vocab:id-type#household_id|HH-1", "membership-role": "head" });

---

searchServicePoint

searchServicePoint([query], [options]) ⇒ Operation

Search service points.

Param	Type	Description
[query]	object	OpenSPP search parameters, eg { country: "PH" }. See the OpenSPP service point docs
[options]	object	count, offset

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

searchServicePoint({ country: "PH", contractActive: true });

---

unenroll

unenroll(beneficiary, programId, [options]) ⇒ Operation

Unenroll a registrant from a program by setting their membership to exited. If the membership isn't enrolled, returns it unchanged. Throws if the registrant has no membership in this program, or also has memberships in other programs, because the adaptor can't be sure OpenSPP would update the membership for this program.

Param	Type	Description
beneficiary	string	Typed reference: Individual/system|value or Group/system|value
programId	string	Program identifier as system|value
[options]	object	exitDate (YYYY-MM-DD), exitReason (CodeableConcept; OpenSPP doesn't save it)

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

unenroll("Individual/urn:openspp:vocab:id-type#national_id|PH-123", "urn:openspp:program|universal-child-grant");

Example: With exit details

unenroll("Group/urn:openspp:vocab:id-type#household_id|HH-1", "urn:openspp:program|cash-transfer", { exitDate: "2026-09-30" });

---

updateGroup

updateGroup(id, data, [options]) ⇒ Operation

Update some fields of a group. Fields you leave out are unchanged, and null clears a field.

Param	Type	Description
id	string	Identifier as system|value
data	object	Fields to change
[options]	object	ifMatch: ETag from a previous read, to fail if the record changed

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

updateGroup("urn:openspp:vocab:id-type#household_id|HH-1", { name: "Santos-Reyes Household" });

---

updateIndividual

updateIndividual(id, data, [options]) ⇒ Operation

Update some fields of an individual. Fields you leave out are unchanged, and null clears a field.

Param	Type	Description
id	string	Identifier as system|value
data	object	Fields to change
[options]	object	ifMatch: ETag from a previous read, to fail if the record changed

This operation writes the following keys to state:

State Key	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

Example

updateIndividual("urn:openspp:vocab:id-type#national_id|PH-123456789", { birthDate: "1985-03-16" });

---

Interfaces

OpenSPPState

State object

Properties

Name	Description
data	the parsed response body. For searches, the list of resources.
response	the response from the HTTP server, including headers and statusCode. Searches add page, with total and next.
references	an array of all previous data objects used in the Job

---

ProgramOptions

Options for getPrograms

Properties

Name	Type	Description
[name]	string	Filter by name
[status]	'active' | 'ended'	Filter by status
[targetType]	'individual' | 'group'	Filter by target type
[count]	number	Page size, 1-100 (OpenSPP default 20)
[lastId]	number | string	Cursor for the next page: the _lastId value in state.response.page.next

---

SearchOptions

Options for OpenSPP searches

Properties

Name	Type	Description
count	number	Page size, 1-100 (OpenSPP default 20)
offset	number	Number of records to skip
sort	string	Individuals only: one of name, birthDate or lastUpdated, with a - prefix for descending
elements	string | Array.<string>	Only return these fields (individuals and groups)
extensions	string | Array.<string>	Include these extensions (individuals and groups)

---