> 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/client-api.md).

# Client API

PEARS now offers an API, allowing your organization's other software to exchange data with PEARS automatically.

PEARS now has an **API** — a way for your organization's other software systems to send data to PEARS and pull data out of it automatically, without anyone typing it in by hand.

This page explains what that means and what it can be used for. It isn't a technical guide; the detailed instructions your developer will need are published separately, and are linked at the bottom.

{% hint style="warning" %}
**NOTE:** The API is released with the **PEARS Data Connect** add-on. If **Organization Settings → API Keys** shows a "Coming soon" message, your organization isn't enabled yet — [contact PEARS support](/contact-us.md) to learn more or request access.
{% endhint %}

## What Is an API?

The PEARS website is built for people. You sign in, fill out a form, click **Save**, and PEARS stores your record.

An API is the same thing built for software. It gives another program a defined set of requests it can make — "create this program activity," "give me every success story from last quarter" — and PEARS answers them directly. No browser, no forms, no one clicking through screens.

The practical difference is scale and repetition. A person entering 400 records is a week of tedious work. A program doing it through the API is a few minutes, and it can run again next month without anyone remembering to do it.

<details>

<summary>GLOSSARY: Terms you may hear</summary>

* **API** — Application Programming Interface. The set of requests one piece of software can make of another.
* **API key** — A long, secret string of characters that identifies your organization to the API, like a password for a program rather than a person. Anyone holding it can read and change your organization's PEARS data, so it's treated like a credential.
* **Integration** — A connection built between two systems so they exchange data automatically.
* **Endpoint** — One specific thing the API can do, such as "list program activities." Developers use this term constantly; it just means one available request.

</details>

## What It Can Be Used For

The API doesn't add new capabilities to PEARS so much as it removes the need to do things by hand. Common uses:

* **Stop double entry.** If your staff already record classes or events in another system, that system can create the matching PEARS records itself, instead of someone re-keying them.
* **Bring history in.** Moving from a legacy database or a pile of spreadsheets? The data can be loaded in bulk rather than entered record by record.
* **Keep contacts in sync.** When someone updates a contact in your CRM, the same update can flow into PEARS automatically.
* **Feed dashboards and reports.** Your data team can pull PEARS data on a schedule into a warehouse, a BI tool, or an institutional reporting system.
* **Automate the routine.** Recurring cleanup, quality checks, or status updates can be scripted once and then run on their own.
* **Connect an AI tool.** Because the API is a structured, documented way in and out of PEARS, an AI assistant can be pointed at it and given your API key.

That last one is worth a closer look, because it's the newest and the least familiar. An assistant connected to the API can answer questions about your data in plain language — "how many youth did we reach in Jackson County last quarter?" — without anyone building a report first. It can also work in the other direction, drafting records from notes or a spreadsheet for a person to check and approve.

Two things to keep in mind. An AI assistant connected this way is acting with your API key, so it can change real records, not just read them — most organizations start it out reading only, and add the ability to write once they trust it. And this is separate from the [AI Tools](/administration/administration/ai-tools.md) built into PEARS: those are part of the product and ready to use, while an outside assistant is something your organization chooses, configures, and remains responsible for, including whatever data gets shared with it.

{% hint style="warning" %}
**NOTE:** Program participant data is sensitive. Before connecting an outside AI tool, check what your institution's policies allow and what the tool does with the information you send it.
{% endhint %}

{% hint style="info" %}
**TIP:** A good rule of thumb — if someone on your team does the same repetitive thing in PEARS every week, or copies data between PEARS and another system, that's a candidate for the API.
{% endhint %}

## What's Supported Today

The API is being released module by module. Here's where it stands.

### Modules You Can Create and Update

| Module             | Notes                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Program Activities | The full record, including sessions, demographics, collaborators, partners, and reading (not writing) of attached surveys |
| Success Stories    | The full record, including the narrative, keywords, collaborators, and partners                                           |
| CRM Contacts       | Including demographics and communication preferences                                                                      |
| CRM Interactions   | Logged against existing contacts                                                                                          |

### Information You Can Look Up

Your developers can also read your organization's supporting data — sites, units, reporting periods, program areas, users, surveys, custom field questions, and the various lists PEARS uses to fill dropdowns.

{% hint style="warning" %}
**NOTE:** This supporting data is **read-only** through the API. Sites, lists, reporting periods, and custom fields are still managed in PEARS by an administrator. The API can see them so it knows what values are valid, but it can't change them.
{% endhint %}

## Things Worth Knowing

A few points that tend to come up when organizations plan an integration.

* **Access is per organization.** Each API key works with exactly one organization's data. It can't reach another organization's records.
* **The same rules apply.** The API follows the same requirements as the web interface. A record still needs its required sections filled in before it can be marked complete, and it can't skip validation just because software created it.
* **Records can be credited to a real person.** By default, records created through the API are attributed to an automated account. Your developer can instead attribute each record to a specific PEARS user, so ownership and reporting look the way they would if that person had entered it. PEARS keeps its own audit record of the automation either way.
* **There are usage limits.** To keep the system healthy for everyone, each key is capped on how many requests it can make per minute and per day. The limits are generous for normal use, and your developer will find the specifics in the technical documentation.
* **It's a real project.** Connecting two systems takes a developer, some planning, and testing. It isn't a setting you switch on — but once built, it runs on its own.

## Getting Started

{% stepper %}
{% step %}

### Talk to us about access

[Contact PEARS support](/contact-us.md) to confirm your organization is enabled for the API and to discuss what you're hoping to connect.
{% endstep %}

{% step %}

### Create an API key

Once enabled, an organization administrator generates a key in Organization Settings under **General → API Keys**. The key is shown only once, when it's created — copy it somewhere safe before closing the window.
{% endstep %}

{% step %}

### Hand it to your developer

Give the key to whoever is building the integration, along with the link to the technical documentation below. Treat it like a password: share it privately, and revoke it from the same page if it's ever exposed or the project ends.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**NOTE:** An API key can read and change your organization's PEARS data. Don't email it, paste it into a shared document, or post it in a group chat.
{% endhint %}

## Technical Documentation

Your developers will want the full reference, which lists every available request, the exact information each one expects, and a console for trying them out. It's published with PEARS itself:

```
https://pears.io/api/v1/docs/
```

That reference is the authoritative source and stays current as the API grows. This page won't repeat it.

{% hint style="info" %}
**TIP:** If your developer can't reach that page, [contact PEARS support](/contact-us.md) — access to the documentation is granted alongside your organization's API keys.
{% endhint %}

## Related Pages

* [Data Mart](/analyze/data-mart.md) — Query PEARS data directly from Power BI, R, or another reporting tool
* [Organization Settings](/administration/administration/organization-settings.md) — Where API keys are created and managed