# CRM API

Search, create and update HubSpot contacts, log notes and WhatsApp conversations, move deals and list owners through the Zernio API.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The [CRM API](/crm/search-crm-contacts) acts on the connected HubSpot portal: the same requests work for Salesforce, so one integration covers both. Every call reads or writes HubSpot directly; Zernio stores nothing.

| Call | What it does in HubSpot |
|---|---|
| [Search contacts](/crm/search-crm-contacts) | Contacts search by text, email or phone |
| [Get](/crm/get-crm-contact), [create](/crm/create-crm-contact), [update](/crm/update-crm-contact) a contact | Contact records |
| [Log an activity](/crm/create-crm-activity) | A Communication for WhatsApp and SMS, a Note for anything else |
| [List](/crm/list-crm-deals), [get](/crm/get-crm-deal), [update](/crm/update-crm-deal) deals | Deals, with their associated contacts |
| [List owners](/crm/list-crm-owners) | HubSpot owners, for `ownerId` |

## Before you start

Connect HubSpot ([Connect](/platforms/hubspot/connect)) and use its account id as `accountId`. Contacts and activities work on every connection.

Deals and owners need optional scopes that the portal approves when it connects:

- `crm.objects.deals.read` to read deals, `crm.objects.deals.write` to update them.
- `crm.objects.owners.read` to list owners.

A portal that connected before they existed answers `403` with code `crm_scope_missing`. Reconnect HubSpot and approve them on the consent screen. The account id stays the same.

## Find a contact

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data } = await zernio.crm.searchCrmContacts({
  path: { accountId: 'ACCOUNT_ID' },
  query: { phone: '+14155550100', properties: 'lifecyclestage' },
});
const contact = data.contacts[0];
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

result = client.crm.search_crm_contacts(
    account_id="ACCOUNT_ID",
    phone="+14155550100",
    properties="lifecyclestage",
)
contact = result["contacts"][0]
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/crm/ACCOUNT_ID/contacts/search?phone=%2B14155550100&properties=lifecyclestage" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Send one of `q`, `email` or `phone`. A phone matches however the contact saved it, with or without the country code. `properties` returns the HubSpot properties you name, by internal name.

## Create a contact and log a conversation

```bash
curl -X POST "https://zernio.com/api/v1/crm/ACCOUNT_ID/contacts" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Maria", "lastName": "Garcia", "email": "maria@example.com", "properties": { "lifecyclestage": "lead" } }'

curl -X POST "https://zernio.com/api/v1/crm/ACCOUNT_ID/contacts/CONTACT_ID/activities" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Asked for the annual plan price.", "channel": "whatsapp", "direction": "inbound" }'
```

`channel: whatsapp` or `sms` logs a Communication on the contact's timeline, any other channel a Note.

An email that already belongs to a contact answers `409` with code `crm_duplicate_record` and that contact in `details.existingId`. A property your portal requires answers `422` with code `crm_validation_failed`.

## Move a deal

```bash
curl -X PATCH "https://zernio.com/api/v1/crm/ACCOUNT_ID/deals/DEAL_ID" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "closedwon", "amount": 4800, "closeDate": "2026-11-30" }'
```

`stage` is the stage's internal id (`closedwon`, `appointmentscheduled`, or your pipeline's own). List deals in a stage with `GET /v1/crm/ACCOUNT_ID/deals?stage=closedwon`, newest change first.

## Platform fields

| Unified field | HubSpot property |
|---|---|
| `firstName`, `lastName`, `email`, `phone`, `company` | `firstname`, `lastname`, `email`, `phone` (else `mobilephone` on reads), `company` |
| `ownerId` | `hubspot_owner_id` |
| Deal `name`, `stage`, `amount`, `currency`, `closeDate` | `dealname`, `dealstage`, `amount`, `deal_currency_code`, `closedate` |

Any other property goes in `properties` by internal name, up to 50 per request.

## How it behaves

- Calls share the portal's HubSpot rate limit with the conversation sync. Past it, the API answers `429` with `Retry-After`.
- Writes answer with the record read back from HubSpot, so you see what HubSpot stored.
- `url` opens the record in HubSpot. An activity's `url` opens its contact.

## Related

- [Search CRM contacts](/crm/search-crm-contacts)
- [Contact sync](/platforms/hubspot/sync)
- [Salesforce CRM API](/platforms/salesforce/crm-api)