> ## Documentation Index
> Fetch the complete documentation index at: https://help.reevo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Public API v2

> Use Reevo's Public API v2 to read and write accounts, contacts, opportunities, tasks, notes, activities, meetings, emails, and custom objects with an API key.

Public API v2 is the newer version of Reevo's REST API. It covers more of your CRM than the original API: you can read and write accounts, contacts, opportunities, tasks, notes, and custom objects, log calls, meetings, and emails as activities, read meetings with their recordings and transcripts, read email threads, and look up the fields available on every object in your workspace.

The original API keeps working alongside v2. If you have an existing integration built on it, see [API Integrations with Other Tools](https://help.reevo.ai/Data-management-and-migration/Integrations-With-Other-Tools.md).

***

## Before you start

* **An API key.** A workspace admin creates API keys in [**Settings → Integrations → API keys**](https://app.reevo.ai/settings/integrations). The same keys work for both API versions. The steps for creating, managing, and expiring a key are in the API Integrations with Other Tools article linked above.
* **The right permissions on the key.** Each v2 request checks that the key has the Read or Write permission for the object it touches. A request without it is refused with an `insufficient_scope` error.

***

## Base URL and reference documentation

Send every v2 request to this base URL:

```
https://api.reevo.ai/api/v2/public
```

The full, interactive reference for every endpoint, field, and error lives here:

* **Interactive reference:** [api.reevo.ai/api/v2/public/docs](https://api.reevo.ai/api/v2/public/docs)
* **OpenAPI specification:** [api.reevo.ai/api/v2/public/openapi.json](https://api.reevo.ai/api/v2/public/openapi.json)

Load the OpenAPI specification into Postman, an API client, or a code generator to get every endpoint and request shape at once.

***

## Authenticate your requests

Pass your API key as a bearer token in the `Authorization` header:

```bash theme={null}
curl "https://api.reevo.ai/api/v2/public/_me" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The `X-Api-Key` header used by the original API is also accepted, so an existing integration can switch its URLs to v2 without changing how it sends the key.

> [!TIP]
>
> **Check your setup first.** `GET /_me` describes the key you are calling with: its user, organization, permissions, and request limits. A successful response confirms that the key is valid.

***

## What you can do with v2

| Object | What v2 supports |
| :- | :- |
| **Accounts** | Create, read, update, archive, upsert by domain, query, manage domains, and link contacts. |
| **Contacts** | Create, read, update, archive, upsert by email, query, manage emails and phone numbers, and link accounts and opportunities. |
| **Opportunities** | Create, read, update, archive, query, and link contacts. |
| **Tasks** | Create, read, update, archive, and query. |
| **Notes** | Create, read, update, and query, with links to contacts, accounts, opportunities, or a meeting. Notes cannot be archived through the API. |
| **Activities** | Log a call, meeting, email, or other interaction, and query a record's activity timeline. |
| **Meetings** | Read and query meetings, and get links to a meeting's recording and transcript. |
| **Emails** | Read an email thread, read a single message with its body as plain text, and page through a thread's messages. |
| **Users and teams** | Read and query users and teams, and see team membership. |
| **Custom objects** | Create, read, update, archive, upsert, and query records of your workspace's custom objects. |

Custom objects use paths that start with `cus_obj__` followed by the object's API name, for example `/cus_obj__project`. Every record also exposes its custom fields by their API names.

***

## Find the fields for each object

Field names in v2 match each object's schema in your workspace, including your custom fields. Two endpoints describe them:

* `GET /_organization_schema_summary` lists every object available in your workspace.
* `GET /_schema/{record_type}` describes one object's fields, for example `GET /_schema/contact`.

Check the schema before you build filters or write requests. A field that does not exist is rejected with an error that names it, rather than being silently ignored.

***

## Read records

Read a single record by its ID:

```bash theme={null}
curl "https://api.reevo.ai/api/v2/public/contact/CONTACT_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

To list records, send a `POST` to the object's `_query` endpoint. You can filter, sort, and page through the results:

```bash theme={null}
curl -X POST "https://api.reevo.ai/api/v2/public/contact/_query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "primary_email", "operator": "ends_with", "value": "@example.com" }
    ],
    "sort": [ { "field": "created_at", "direction": "desc" } ],
    "limit": 50
  }'
```

* **Filters** are a list of conditions with a `field`, an `operator`, and a `value`. Combine conditions with `and`, `or`, and `not`. Operators include `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, `not_in`, `exists`, `not_exists`, `contains`, `starts_with`, `ends_with`, `contains_any`, and `contains_none`.
* **Page size** is set with `limit`, from 1 to 100. The default is 50.
* **Paging:** each response includes a `pagination` block. To get the next page, send the same request with `cursor` set to the `next_cursor` value from the previous response. When `next_cursor` is `null`, you have reached the last page.

***

## Create and update records

* **Create** a record with a `POST` to the object's path, for example `POST /contact`. Put the fields in an `attributes` object.
* **Update** a record with a `PATCH` to its path, for example `PATCH /contact/CONTACT_ID`. Send only the fields you want to change.
* **Upsert** a record with a `POST` to the object's `_upsert` endpoint. Reevo looks for an existing record that matches the `match` field. If it finds one, it updates it and returns `200`. If it does not, it creates a new record and returns `201`.

This request updates the contact with the email `jordan@example.com`, or creates one if none exists:

```bash theme={null}
curl -X POST "https://api.reevo.ai/api/v2/public/contact/_upsert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "match": { "field": "primary_email", "value": "jordan@example.com" },
    "attributes": {
      "first_name": "Jordan",
      "last_name": "Example",
      "title": "Head of Operations",
      "stage": { "value_type": "select", "value": { "api_name": "default" } }
    }
  }'
```

> [!NOTE]
>
> Leave the matched field out of `attributes`. Reevo applies the matched value automatically, and it cannot be changed in the same request.

***

## Handle errors

Every error response has the same shape, so your integration can branch on the `code` field:

```json theme={null}
{
  "status_code": 403,
  "error_type": "forbidden",
  "code": "insufficient_scope",
  "message": "A human-readable summary of the error."
}
```

Some errors also include a `details` object, for example the name of a field that does not exist. Common codes:

| Code | What it means |
| :- | :- |
| **`missing_api_key`** / **`invalid_api_key`** | The request has no API key, or the key is not valid. Check the `Authorization` header. |
| **`insufficient_scope`** | The key does not have the Read or Write permission this request needs. |
| **`unknown_field`** | A field in the request does not exist on the object. Check the object's schema. |
| **`record_not_found`** | No record with that ID exists in your workspace. |
| **`ambiguous_match`** | An upsert matched more than one existing record. |
| **`duplicate_record`** | A record with the same unique value already exists. |
| **`stage_entrance_criteria_not_met`** | The record does not meet the entrance criteria for the stage you asked for. |
| **`limit_out_of_range`** | The `limit` in a query is outside 1 to 100. |
| **`rate_limit_exceeded`** / **`quota_exceeded`** | Your organization sent requests too quickly or used its request allowance. |

***

## Request limits

Public API v2 requests count toward the same limits as the original API: a per-second speed limit and, depending on your plan, an allowance of requests for each billing period. Both apply to your whole organization. See [API and MCP request limits](https://help.reevo.ai/Getting-started/Organizational-Account-Settings/Usage.md#api-and-mcp-request-limits) for how the limits work and where to check your usage.

***

## Troubleshooting / FAQs

> [accordion] Do I need a new API key for v2?
>
> No. The same API keys work for both versions. Make sure the key has the Read or Write permissions for the objects you want to use.

> [accordion] Can I keep using the original API?
>
> Yes. The original API keeps working, and existing integrations built on it do not need to change. Its endpoints are documented in API Integrations with Other Tools.

> [accordion] Why is my query rejected when I filter on a field?
>
> v2 rejects a field that does not exist on the object instead of ignoring it. Check the exact field name with `GET /_schema/{record_type}`, for example `GET /_schema/contact`.

> [accordion] Can I read AI-generated summaries through the API?
>
> No. Neither API version returns Reevo's AI-generated deal, meeting, or activity summaries.

***

Ready to connect? Open [**Reevo**](https://app.reevo.ai) to create your API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.