Ctrlk
Contact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.
RSS feed

API Changelog

A version-by-version record of changes to the PEARS Client API: endpoints, fields, parameters, and behavior.

This page records changes to the PEARS Client API in reverse chronological order: endpoints, fields, and query parameters added, removed, or changed. It is written for the developers integrating with /api/v1/, so it uses the exact endpoint paths and field names from the technical reference.

Releases without Client API changes are not listed. The main Changelog links here from each release that has them.

NOTE: The Client API was released to client organizations in version 26.12.0, which is the earliest entry below. Endpoints that existed in earlier releases were not reachable by client organizations and are not recorded here.

Released

26.16.0

New Fields and Parameters

From Reporting Year 2027, PEARS collects race and ethnicity as one combined question in place of the separate race and ethnicity questions. A program activity with a 2027-or-later reporting period records its participants in the fields below and leaves the separate ethnicity_*, race_*, onerace_* and multrace_* fields empty; activities in earlier reporting periods keep using those fields, which are unchanged.

  1. /api/v1/program-activities/

    • demographics.race_ethnicity_one_american_indian_alaskan_native, demographics.race_ethnicity_one_asian, demographics.race_ethnicity_one_black, demographics.race_ethnicity_one_hispanic_latino, demographics.race_ethnicity_one_middle_eastern_north_african, demographics.race_ethnicity_one_hawaiian_pacific_islander, demographics.race_ethnicity_one_white — Number of participants reporting that category as their only race or ethnicity.

    • demographics.race_ethnicity_mult_american_indian_alaskan_native, demographics.race_ethnicity_mult_asian, demographics.race_ethnicity_mult_black, demographics.race_ethnicity_mult_hispanic_latino, demographics.race_ethnicity_mult_middle_eastern_north_african, demographics.race_ethnicity_mult_hawaiian_pacific_islander, demographics.race_ethnicity_mult_white — Number of participants reporting that category among two or more races or ethnicities.

    • demographics.race_ethnicity_two_or_more — Number of unique participants reporting two or more races or ethnicities.

    • demographics.race_ethnicity_prefer_not_to_respond — Number of participants who preferred not to report a race or ethnicity.

    • demographics.race_ethnicity_unknown — Number of participants whose race or ethnicity is unknown.

Changed — Action Required

These changes alter how existing requests behave. Review any integration that depends on them.

  1. /api/v1/people/

    • demographics.ethnicity — Now read-only. The stored value is still returned, but a submitted one is ignored; record Hispanic or Latino under demographics.race instead.

    • demographics.race — Now accepts the combined race and ethnicity categories, including Hispanic or Latino and Middle Eastern or North African. IDs come from /api/v1/races/. A person's stored selections stay accepted even after a category is retired.

  2. /api/v1/program-activities/

    • demographics — The rule set now follows the activity's reporting periods. An activity with a 2027-or-later reporting period must leave the separate ethnicity_*, race_*, onerace_* and multrace_* fields empty, and an earlier activity must leave the race_ethnicity_* fields empty; a value in a field that does not apply is rejected with This field is not part of this program's demographics and must be set to NULL. The combined counts are validated like the web form: the single-category counts, race_ethnicity_two_or_more, race_ethnicity_prefer_not_to_respond and race_ethnicity_unknown together equal total, and no race_ethnicity_mult_* count exceeds race_ethnicity_two_or_more.

  3. /api/v1/races/

    • Now lists the combined race and ethnicity categories: Hispanic or Latino and Middle Eastern or North African are added, and Native Hawaiian or Other Pacific Islander is renamed Native Hawaiian or Pacific Islander. Results are returned in display order rather than by ID.

    • is_active (query parameter) — false now adds retired categories to the list rather than returning every row. On every lookup endpoint with dated availability windows, is_active=false no longer returns values whose window has not opened yet.

26.15.0

Removed Fields and Parameters

These fields are no longer returned in responses, and values sent for them are ignored. Query parameters listed here are no longer applied.

  1. /api/v1/people/

    • unit — Removed with the CRM redesign. A person's organization is now the free-text external_organization_name.

    • unit (query parameter) — Removed along with the field. The remaining filters are site, gender, age, ethnicity, and is_active.

New Fields and Parameters

  1. /api/v1/people/

    • external_organization_name — Free-text name of the organization this person is affiliated with. The successor to the site link.

    • partners — IDs of the partner organizations this person is linked to. Read-only, because partner records are not yet available through the API.

  2. /api/v1/interactions/

    • partners — IDs of the partner organizations credited on this interaction. Read-only, for the same reason.

    • action_plans — IDs of the action plans this interaction was credited to. Read-only, because action plans are not yet available through the API.

Deprecated — Action Required

Still supported for now, but scheduled for removal in a future release. Remove all references from your integration.

  1. /api/v1/interactions/

    • is_note_private — Superseded by record sharing, which is now the source of truth for who can see an interaction's notes. The field is still written for existing integrations.

26.12.0

New Endpoints

The Client API is now available to organizations with the PEARS Data Connect add-on. Requests carry an API key, the version is the /api/v1/ path prefix, and list responses are paginated with a cursor. See Client API for what it is and how to request access, and the technical reference for every field.

Records you can create and change. Updates are sent with PATCH; PUT is not accepted.

  • /api/v1/program-activities/ (GET, POST, PATCH, DELETE) — Program activities. Sessions, demographics, collaborators, partners, and surveys ride in the activity payload as nested sections rather than separate routes.

  • /api/v1/success-stories/ (GET, POST, PATCH, DELETE) — Success stories, with their collaborators and keywords.

  • /api/v1/people/ (GET, POST, PATCH, DELETE) — People in your organization's CRM.

  • /api/v1/interactions/ (GET, POST, PATCH, DELETE) — Interactions logged against CRM people.

Marking a record complete:

  • PATCH /api/v1/program-activities/{id}/toggle_status/ and PATCH /api/v1/success-stories/{id}/toggle_status/ — Move a record between complete and incomplete.

Your organization's own data, read-only:

  • /api/v1/sites/ and /api/v1/units/ — Sites and extension units.

  • /api/v1/users/ and /api/v1/user-groups/ — Users in your organization and the groups they belong to.

  • /api/v1/reporting-periods/ — Reporting periods.

  • /api/v1/crm-categories/ — Categories a person can be tagged with.

  • /api/v1/surveys/ — Surveys.

  • /api/v1/keywords/ — Success story keywords.

  • /api/v1/custom-data/ — The custom-field questions configured for a module type.

Reference lists, read-only. These supply the IDs that writable fields expect:

  • /api/v1/program-areas/, /api/v1/audiences/, /api/v1/curricula/, /api/v1/delivery-methods/, /api/v1/funding-sources/, /api/v1/materials/, /api/v1/languages/, /api/v1/indicators/, /api/v1/approaches/

  • /api/v1/ages/, /api/v1/genders/, /api/v1/ethnicities/, /api/v1/races/

  • /api/v1/communication-methods/, /api/v1/crises/, /api/v1/cities/, /api/v1/reach-sources/

  • /api/v1/intervention-channels/, /api/v1/intervention-topics/, /api/v1/socioecological-frameworks/, /api/v1/partner-types/, /api/v1/partnership-contributions/

  • /api/v1/four-h-project-areas/, /api/v1/four-h-delivery-modes/

Service:

  • /api/v1/status/ — Health check. Confirms the key works and echoes the organization it belongs to.

Last updated