canonical: https://jentic.com/apis/helmiq.net/helmiq

# HelmIQ API

The HelmIQ API reads and maintains the contacts, companies, and deals in a HelmIQ CRM workspace. You list and retrieve contacts and companies, create and update them when your key carries the write scopes, and browse deals read-only for pipeline context. All data is scoped to the organization that owns the key, so an application only ever works with its own workspace.

## For AI agents

List, read, create, and update HelmIQ CRM contacts and companies, and read deals, all scoped to one organization by the API key. A compact REST surface for keeping a CRM current.

## Scope

Does not send email, manage tasks, or process payments. Use for reading and maintaining HelmIQ contacts, companies, and deals only.

## Capabilities

- List contacts and retrieve a single contact by id, scoped to your organization
- Create and update contacts when the key carries the write scopes
- List and look up companies, and add or update company records
- Browse deals and retrieve one deal by id, read-only
- Fetch the live OpenAPI document that describes the workspace

## Use cases

### Agent-Maintained CRM Records

An AI agent keeping a CRM tidy uses the HelmIQ API through Jentic to read and update the organization's contacts and companies: it lists contacts, retrieves one by id, and patches details, and it creates or updates company records when the key carries the write scopes. All data is scoped to the organization that owns the key, so the agent only ever sees that workspace. Deals are available read-only for context when qualifying a contact.

Example prompt: List contacts, retrieve one by id, update its details, then look up the related company

### Company and Deal Lookup

A reporting workflow reads the organization's companies and deals to build a snapshot. The HelmIQ API lists companies and deals and retrieves any one of them by id, all scoped to the key's organization. Because deals are read-only here, the workflow can pull pipeline context without risk of changing it.

Example prompt: List companies and deals, then retrieve the full record for one company and one deal by id

### Contact Creation From Inbound Leads

When a lead arrives, an application creates a contact and the company it belongs to in HelmIQ, then updates them as more detail comes in. The API accepts create and update calls on contacts and companies for keys that hold the write scopes, keeping the CRM current without manual entry. Reads stay available even on a read-only key.

Example prompt: Create a company, create a contact linked to it, then update the contact by id

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/contacts` | List contacts |
| POST | `/contacts` | Create a contact |
| PATCH | `/contacts/{id}` | Update a contact by id |
| GET | `/companies` | List companies |
| POST | `/companies` | Create a company |
| GET | `/deals` | List deals |
| GET | `/deals/{id}` | Retrieve a deal by id |

## Key resources

- **Contacts** — List, retrieve, create, and update contacts in your organization
- **Companies** — List, retrieve, create, and update company records
- **Deals** — List and retrieve deals, read-only

## 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:** 70 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 78 / 100
  - Developer Experience & Jentic Compatibility: 70 / 100
  - AI-Readiness & Agent Experience: 55 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 86 / 100
- **View full report:** https://jentic.com/apis/helmiq.net/helmiq/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 the HelmIQ API by hand means issuing an API key, sending it as a bearer token on every request, and tracking which write scopes the key holds before an update. Through Jentic you install once, import it from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** A HelmIQ key is issued with specific scopes, so a read-only key already blocks writes to contacts and companies. A Jentic rule can go further and allow only the operations your agent needs, such as listing and reading records, while leaving create and update out unless you add them.
- **Credential handling:** Your HelmIQ API 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 'list CRM contacts' or 'create a company', and Jentic returns the matching HelmIQ operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Pipedrive** — A full sales CRM with pipeline, activity, and automation features, versus HelmIQ's compact contacts, companies, and deals surface.
- **Attio** — A flexible data-model CRM with custom objects and records, versus HelmIQ's fixed contacts, companies, and deals.
- **Apollo.io** — Enriches and finds contact and company data that can populate HelmIQ records.

## FAQ

### What authentication does the HelmIQ API use?

The HelmIQ API authenticates with an API key sent as a bearer token in the Authorization header, an `hk_live_` key, per its OpenAPI spec. All data is scoped to the organization that owns the key, and write operations require a key that carries the write scopes. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time.

### Can I create and update contacts with the HelmIQ API?

Yes, when your key carries the write scopes. You can create a contact, update one by id, and do the same for companies, while listing and retrieving contacts, companies, and deals works on any key. Deals themselves are read-only.

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

The OpenAPI spec does not specify rate limits. For current limits, see the HelmIQ documentation at https://helmiq.net.

### How do I update a contact through Jentic?

Search Jentic with a query like 'update a CRM contact', add the HelmIQ API from the directory, and store your bearer API key once. Your agent lists contacts, finds the one it needs, and patches it by id, all scoped to your organization. To run it on your own infrastructure, install Jentic One from its GitHub repo.

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

Yes. Start with a read-only HelmIQ key so the agent cannot write at all, then write a Jentic rule that allows only the operations it needs, such as listing and retrieving contacts and companies, and leave create and update out unless you add them, with every call logged. Record ids travel in the URL path, so scoping bounds which operations run.

### Is there a HelmIQ API MCP server?

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