canonical: https://jentic.com/apis/klipy.ai/klipy

# Klipy API

The Klipy API reads and writes the core records in a Klipy CRM: people, companies, and the interactions logged against them. You can create a person by email, upsert one with phone, social handles, and alternate emails, query people by email, phone, companyId, or owner, and create or remove companies by domain. Interactions such as emails, meetings, memos, voice notes, and bookings are logged with a direction and title and can be queried by contact or company, with each endpoint gated by a scope such as people:read or companies:remove.

## For AI agents

Create, upsert, query, and update people and companies in Klipy CRM, and log or query interactions such as emails, meetings, and memos against them.

## Scope

Does not handle deal pipelines, email sending, or support tickets. Use for Klipy people, company, and interaction records only.

## Capabilities

- Upsert a person by email with firstName, lastName, title, phone, linkedin, and altEmails in one call
- Query people by email, phone, companyId, or owner with cursor pagination up to 100 per page
- Create a company from its domain and name, then update or delete it by companyId
- Log an interaction such as EMAIL, MEETING, MEMO, or VOICE_NOTE with a direction and title against a contact
- Query interactions for a contactId or companyId to read the history with an account
- Check which key is in use and that it authenticates with GET /authenticate

## Use cases

### AI agent CRM upkeep through Jentic

An assistant that reads your inbox keeps Klipy current without you copying details by hand. Through Jentic the agent searches for 'upsert a contact', loads the Klipy upsert operation with its input schema, and writes the person by email with the name, title, and phone it found. Your own Jentic One instance injects the klipy_api_ key at call time, so the agent never holds it.

Example prompt: Call PUT /people with email 'ana@globex.com', firstName 'Ana', lastName 'Ruiz', and title 'Head of Ops', then log a MEETING interaction with POST /interactions using mainContactEmail 'ana@globex.com'

### Interaction logging after calls and meetings

After a call or meeting, the notes go into Klipy as an interaction with a type such as MEETING or VOICE_NOTE, a direction such as OUTBOUND, a title, an optional summary, and the interactionDate as a Unix timestamp in milliseconds. Each interaction names its contact by mainContact or mainContactEmail.

Example prompt: Call POST /interactions with type 'MEETING', direction 'OUTBOUND', title 'Renewal check-in', a summary, and mainContactEmail for the attendee

### Account history before a call

Before a call, an agent pulls the people at a company with a companyId filter and then queries interactions for that company, giving a quick history of who was contacted and what was discussed.

Example prompt: Call POST `/people/query` with filter companyId 'cmp_123', then POST `/interactions/query` with filter companyId 'cmp_123' and summarise the latest interactions

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| PUT | `/people` | Upsert a person |
| POST | `/people/query` | Query people |
| PATCH | `/people/{personId}` | Update a person |
| POST | `/companies` | Create a company |
| GET | `/companies/{companyId}` | Get a company by ID |
| POST | `/interactions` | Create an interaction |
| POST | `/interactions/query` | Query interactions |

## Key resources

- **People** — Create, upsert, query, read, update, and delete people
- **Companies** — Create companies by domain and read, update, or delete them by id
- **Interactions** — Create interactions and read or query them by contact or company

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 63 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 64 / 100
  - Developer Experience & Jentic Compatibility: 70 / 100
  - AI-Readiness & Agent Experience: 48 / 100
  - Agent Usability: 94 / 100
  - Security: 55 / 100
  - AI Discoverability: 66 / 100
- **View full report:** https://jentic.com/apis/klipy.ai/klipy/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Klipy by hand means choosing between its X-Klipy-Api-Key header and bearer auth, issuing a key with the right scopes, and unwrapping its object, data, and meta envelopes. Through Jentic you install once, import Klipy from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Klipy puts the person, company, and interaction ids in the URL path (`/people/{personId}`, `/companies/{companyId}`), so a rule can pin your agent to one record and the operations you pick. You choose the operations it may call, so destructive ones like deleting a person or a company are not included unless you add them.
- **Credential handling:** Your Klipy key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upsert a contact' or 'log a meeting', and Jentic returns the matching Klipy operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Attio API** — Flexible CRM with custom objects, lists, and records
- **Affinity API** — Relationship intelligence CRM for dealmaking teams
- **HubSpot CRM Contacts API** — Contact records in the HubSpot CRM

## FAQ

### What authentication does the Klipy API use?

Per its OpenAPI spec, the Klipy API accepts an API key in the format klipy_api_<id>, sent either in the X-Klipy-Api-Key header or as a bearer token in the Authorization header. Each endpoint also requires a scope on the key, such as people:read, companies:write, or interactions:write. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at execution time.

### What are the rate limits for the Klipy API?

Per the Klipy OpenAPI spec, rate limiting is enforced per API key at 200 requests per minute and per organization at 1000 requests per minute. Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, and throttled responses include Retry-After.

### What is the difference between creating and upserting a person in Klipy?

POST /people creates a person from a type of email, an identifier, and a firstName. PUT /people upserts by email and accepts more fields, including phone, personalPhone, linkedin, twitter, altEmails, and remarks, so it is the safer choice when the person may already exist.

### Is there a Klipy MCP server?

You don't need an MCP server to give your agent the Klipy API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls the people, company, and interaction operations on demand without loading another server's tool definitions into its context.

### Can I limit what my agent is allowed to do with the Klipy API?

Yes. For example, write a rule that allows only POST `/people/query`, POST `/interactions/query`, and POST /interactions, so the agent can look people up and log interactions but cannot delete people or companies. Every call it makes through your instance is logged, and you can also issue the key with narrow Klipy scopes.

### How do I log a meeting in Klipy through Jentic?

Search Jentic for 'log a meeting in the CRM', load the Klipy create interaction operation, and call POST /interactions with type MEETING, a direction, a title, and mainContactEmail. To run it on your own infrastructure, install Jentic One from its GitHub repo.