> For the complete documentation index, see [llms.txt](https://support.pears.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.pears.io/updates/api-changelog.md).

# 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](/updates/client-api.md) 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](https://pears.io/api/v1/docs/).

Releases without Client API changes are not listed. The main [Changelog](/changelog.md) links here from each release that has them.

{% hint style="info" %}
**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.
{% endhint %}

## Released

{% updates format="full" %}
{% update date="2026-09-21" %}

## 26.16.0

### <i class="fa-plus">:plus:</i> New Fields and Parameters <a href="#id-26.16.0-new-fields" id="id-26.16.0-new-fields"></a>

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.

### <i class="fa-triangle-exclamation">:triangle-exclamation:</i> Changed — Action Required <a href="#id-26.16.0-changed" id="id-26.16.0-changed"></a>

{% hint style="warning" %}
These changes alter how existing requests behave. Review any integration that depends on them.
{% endhint %}

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.
     {% endupdate %}

{% update date="2026-09-10" %}

## 26.15.0

### <i class="fa-trash">:trash:</i> Removed Fields and Parameters <a href="#id-26.15.0-removed-fields" id="id-26.15.0-removed-fields"></a>

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`.

### <i class="fa-plus">:plus:</i> New Fields and Parameters <a href="#id-26.15.0-new-fields" id="id-26.15.0-new-fields"></a>

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.

### <i class="fa-triangle-exclamation">:triangle-exclamation:</i> Deprecated — Action Required <a href="#id-26.15.0-deprecated" id="id-26.15.0-deprecated"></a>

{% hint style="warning" %}
Still supported for now, but scheduled for removal in a future release. Remove all references from your integration.
{% endhint %}

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.
     {% endupdate %}

{% update date="2026-08-13" %}

## 26.12.0

### <i class="fa-plus">:plus:</i> New Endpoints <a href="#id-26.12.0-new-endpoints" id="id-26.12.0-new-endpoints"></a>

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](/updates/client-api.md) for what it is and how to request access, and the [technical reference](https://pears.io/api/v1/docs/) 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.
  {% endupdate %}
  {% endupdates %}